scheduler.h File Reference

Background job scheduler / delayed task queue for CWIST. More...

#include <cwist/sys/io/cwist_io.h>
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

Include dependency graph for scheduler.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct cwist_scheduler	cwist_scheduler_t
	Opaque background job scheduler handle.
typedef void(*	cwist_scheduler_drop_cb) (void *arg)
	Callback invoked for each pending job that is cancelled.

Functions
cwist_scheduler_t *	cwist_scheduler_create (size_t worker_count, size_t queue_capacity)
	Create a scheduler with a pool of background workers.
void	cwist_scheduler_destroy (cwist_scheduler_t *s)
	Destroy the scheduler and stop all worker threads.
bool	cwist_scheduler_submit (cwist_scheduler_t *s, cwist_job_func func, void *arg)
	Submit a job to be executed as soon as a worker is available.
bool	cwist_scheduler_schedule (cwist_scheduler_t *s, cwist_job_func func, void *arg, uint64_t delay_ms)
	Schedule a job to run after a relative delay.
size_t	cwist_scheduler_pending_count (cwist_scheduler_t *s)
	Number of delayed jobs currently waiting to fire.
size_t	cwist_scheduler_cancel_pending (cwist_scheduler_t *s, cwist_scheduler_drop_cb drop_cb)
	Cancel all delayed jobs that have not yet fired.

Detailed Description

Background job scheduler / delayed task queue for CWIST.

Definition in file scheduler.h.

Typedef Documentation

cwist_scheduler_drop_cb

typedef void(* cwist_scheduler_drop_cb) (void *arg)

Callback invoked for each pending job that is cancelled.

Parameters

arg	The argument that would have been passed to the job function.

Definition at line 65 of file scheduler.h.

cwist_scheduler_t

typedef struct cwist_scheduler cwist_scheduler_t

Opaque background job scheduler handle.

Definition at line 21 of file scheduler.h.

Function Documentation

cwist_scheduler_cancel_pending()

size_t cwist_scheduler_cancel_pending	(	cwist_scheduler_t *	s,
		cwist_scheduler_drop_cb	drop_cb
	)

Cancel all delayed jobs that have not yet fired.

Dequeues every job still waiting on the delayed-job heap. For each job, drop_cb is called with the job's arg so the caller can reclaim any heap-allocated state. If drop_cb is NULL the args are discarded.

Jobs that have already been submitted to the io queue by the timer thread will still run; this function only removes jobs still on the heap.

Safe to call concurrently with cwist_scheduler_schedule(): both operations hold the same mutex.

Parameters

s	Scheduler whose pending jobs are to be cancelled.
drop_cb	Optional destructor called once per cancelled job's arg.

Returns

Number of jobs cancelled.

Detaches the delayed-job heap under s->delayed_mtx and invokes drop_cb(arg) for each cancelled job outside the lock so caller destructors cannot deadlock on scheduler re-entry. Jobs already submitted to the io queue by the timer thread before this call are not affected.

Parameters

s	Scheduler whose pending jobs are to be cancelled.
drop_cb	Destructor called once per cancelled job's arg; may be NULL.

Returns

Number of jobs cancelled.

Definition at line 429 of file scheduler.c.

References cap, and cwist_free().

cwist_scheduler_create()

cwist_scheduler_t * cwist_scheduler_create	(	size_t	worker_count,
		size_t	queue_capacity
	)

Create a scheduler with a pool of background workers.

Parameters

worker_count	Number of worker threads. Must be >= 1.
queue_capacity	Capacity hint forwarded to the underlying io queue.

Returns

Scheduler handle, or NULL on failure.

Create a scheduler with a pool of background workers.

Spawns worker_count worker threads (defaulting to 1 if 0) running the io queue event loop, plus one timer thread for delayed jobs. On any failure, all partially created resources are torn down and freed.

Parameters

worker_count	Number of worker threads; 0 is treated as 1.
queue_capacity	Capacity passed to cwist_io_queue_create().

Returns

The new scheduler, or NULL on allocation or thread-creation failure.

Definition at line 265 of file scheduler.c.

References cap, cwist_alloc(), cwist_alloc_array(), cwist_free(), cwist_full_gc_enabled(), cwist_gc_scope_disown(), cwist_io_queue_create(), and cwist_io_queue_destroy().

Referenced by cwist_app_use_scheduler().

cwist_scheduler_destroy()

void cwist_scheduler_destroy

(

cwist_scheduler_t *

s

)

Destroy the scheduler and stop all worker threads.

Pending immediate jobs are drained before shutdown. Delayed jobs that have not yet fired are dropped.

Destroy the scheduler and stop all worker threads.

Stops the timer and worker threads (waiting for them to finish), then destroys the io queue and frees the heap, worker array, and scheduler. Safe to call with NULL.

Parameters

s	Scheduler to destroy.

Definition at line 327 of file scheduler.c.

References cap, cwist_free(), cwist_io_queue_destroy(), and cwist_io_queue_stop().

Referenced by cwist_app_destroy(), and cwist_app_use_scheduler().

cwist_scheduler_pending_count()

size_t cwist_scheduler_pending_count

(

cwist_scheduler_t *

s

)

Number of delayed jobs currently waiting to fire.

Number of delayed jobs currently waiting to fire.

Does not include jobs already submitted to the io queue.

Parameters

s	Scheduler to query.

Returns

Number of pending delayed jobs; 0 if s is NULL.

Definition at line 412 of file scheduler.c.

References cap.

cwist_scheduler_schedule()

bool cwist_scheduler_schedule	(	cwist_scheduler_t *	s,
		cwist_job_func	func,
		void *	arg,
		uint64_t	delay_ms
	)

Schedule a job to run after a relative delay.

Parameters

delay_ms

Milliseconds to wait before executing the job.

Returns

true on success, false on failure.

Schedule a job to run after a relative delay.

With a zero delay the job is submitted immediately as with cwist_scheduler_submit(). Otherwise it is pushed onto the delayed-job min-heap and the timer thread runs it once the deadline passes.

Parameters

s	Scheduler to schedule on.
func	Job function to run.
arg	Opaque argument passed to func.
delay_ms	Delay in milliseconds before execution; 0 means immediate.

Return values

true	if the job was scheduled.
false	if s or func is NULL, the scheduler is not running, or heap insertion failed (e.g. out of memory).

Definition at line 380 of file scheduler.c.

References cap, and cwist_io_queue_submit().

Referenced by cwist_async_set_timeout().

cwist_scheduler_submit()

bool cwist_scheduler_submit	(	cwist_scheduler_t *	s,
		cwist_job_func	func,
		void *	arg
	)

Submit a job to be executed as soon as a worker is available.

Returns

true on success, false when the scheduler is stopping or OOM.

Submit a job to be executed as soon as a worker is available.

Parameters

s	Scheduler to submit to.
func	Job function to run.
arg	Opaque argument passed to func.

Return values

true	if the job was submitted.
false	if s or func is NULL, the scheduler is not running, or the queue submission failed.

Definition at line 360 of file scheduler.c.

References cwist_io_queue_submit().