You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+58-11Lines changed: 58 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -56,31 +56,78 @@ You can find a full example (the same as above plus a more detailed example) in
56
56
57
57
---
58
58
59
-
## New queuer
59
+
## NewQueuer
60
60
61
-
The `NewQueuer` function initializes a new Queuer instance, setting up the core components for job processing.
61
+
`NewQueuer` is a convenience constructor that creates a new Queuer instance using default database configuration derived from environment variables. It acts as a wrapper around `NewQueuerWithDB`.
62
+
`NewQueuerWithDB` is the primary constructor for creating a new Queuer instance. It allows for explicit database configuration and initializes all necessary components, including database handlers, internal event listeners, and the worker.
- `name`: A `string` identifier for this queuer instance.
71
+
- `maxConcurrency`: An `int` specifying the maximum number of jobs this queuer can process concurrently.
72
+
- `dbConfig`: An optional `*helper.DatabaseConfiguration`. If nil, the configuration will be loaded from environment variables.
73
+
- `options`: Optional `OnError` configurations to apply to the worker.
74
+
75
+
This function performs the following setup:
76
+
- Initializes a logger.
77
+
- Sets up the database connection using the provided `dbConfig` or environment variables.
78
+
- Creates `JobDBHandler` and `WorkerDBHandler` instances for database interactions.
79
+
- Initializes internal `core.Listener` instances for `jobInsert`, `jobUpdate`, and `jobDelete` events.
80
+
- Creates and inserts a new `model.Worker` into the database based on the provided `name`, `maxConcurrency`, and `options`.
81
+
- If any critical error occurs during this initialization (e.g., database connection failure, worker creation error), the function will log a panic error and exit the program. It returns a pointer to the newly configured `Queuer` instance.
82
+
83
+
---
84
+
85
+
## Start
86
+
87
+
The Start method initiates the operational lifecycle of the Queuer. It sets up the main context, initializes database listeners, and begins the job processing and polling loops in a dedicated goroutine.
- `name`: A string identifier for this specific queuer instance. This is useful for distinguishing between multiple queuers in your application or logs.
68
-
- `maxConcurrency`: An integer representing the maximum number of jobs that this queuer can process concurrently. This controls the worker's parallelism.
69
-
- `opts ...WorkerOption`: Optional `WorkerOption` configurations that allow you to customize the worker's behavior, such as error handling strategies.
93
+
- `ctx`: The parent context.Context for the queuer's operations. This context will control the overall lifetime of the queuer.
94
+
- `cancel`: The context.CancelFunc associated with the provided ctx. This function should be called to gracefully stop the queuer.
95
+
96
+
Upon calling Start:
97
+
- It performs a basic check to ensure internal listeners are initialized.
98
+
- Db listeners and broadcasters are created to listen to job events (inserts, updates, deletes).
99
+
- It starts a poller to periodically poll the database for new jobs to process (5 minute interval).
100
+
- It signals its readiness via an internal channel, ensuring the `Start` method returns only when the core loops are active.
101
+
102
+
The method includes a timeout mechanism (5 seconds) to detect if the queuer fails to start its internal processes promptly, panicking if the timeout is exceeded.
103
+
If the queuer is not not properly initialized (created by calling `NewQueuer`), or if there's an error creating the database listeners, the function will panic.
104
+
105
+
---
106
+
107
+
## StartWithoutWorker
108
+
109
+
The `StartWithoutWorker` method provides a way to start the `Queuer` instance without an active worker. This is particularly useful for scenarios where you need to interact with the job queue (e.g., add jobs, check job status) but don't intend for this specific instance to actively process them.
This function handles the entire setup process: it establishes the database connection, configures the necessary job listeners, and creates an associated worker. If any part of this initialization fails, `NewQueuer` will log a panic error and exit the program to prevent an improperly configured queuer from running. It returns a pointer to the newly created `Queuer` instance, ready to accept and process jobs.
115
+
- `ctx`: The parent context.Context for the queuer's operations.
116
+
- `cancel`: The context.CancelFunc associated with the provided ctx.
117
+
- `withoutListeners`: A `bool` flag. If true, the database.NewQueuerDBListener instances for job and job_archive tables will not be created.
118
+
- `dbConnection`: An optional existing `*sql.DB` connection to use. If provided, the queuer will use this connection; otherwise, it will create a new one based on environment variables.
72
119
73
120
---
74
121
75
-
## New queuer without worker
122
+
## Stop
76
123
77
-
The `NewQueuerWithoutWorker` function provides a way to initialize a `Queuer` instance without an active worker. This is particularly useful for scenarios where you need to interact with the job queue (e.g., add jobs, check job status) but don't intend for this specific instance to actively process them.
124
+
The `Stop` method gracefully shuts down the Queuer instance, releasing resources and ensuring ongoing operations are properly concluded.
78
125
79
126
```go
80
-
func NewQueuerWithoutWorker() *Queuer
127
+
func (q *Queuer) Stop() error
81
128
```
82
129
83
-
This function only initializes the database connection and job listeners. It omits the worker component, making it suitable for services that might, for example, serve job status endpoints or solely add jobs to the queue, without consuming computational resources for job execution. Similar to `NewQueuer`, any initialization errors will result in a panic and program exit. It returns a pointer to the newly created `Queuer` instance.
130
+
The `Stop` method cancels all jobs, closes db listeners and returns an error if any step of the stopping process encounters an issue
0 commit comments