scheduler.c File Reference

Background job scheduler with delayed execution. More...

#include <stdatomic.h>
#include <cwist/sys/job/scheduler.h>
#include <cwist/core/mem/alloc.h>
#include <cwist/core/mem/gc.h>
#include <pthread.h>
#include <time.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>

Include dependency graph for scheduler.c:

Go to the source code of this file.

Macros
#define	_POSIX_C_SOURCE   200809L
#define	CWIST_SCHEDULER_HEAP_INIT   16

Functions
cwist_scheduler_t *	cwist_scheduler_create (size_t worker_count, size_t queue_capacity)
	Create a scheduler with worker and timer threads.
void	cwist_scheduler_destroy (cwist_scheduler_t *s)
	Destroy a scheduler and free all its resources.
bool	cwist_scheduler_submit (cwist_scheduler_t *s, cwist_job_func func, void *arg)
	Submit a job for immediate execution by a worker thread.
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 delay.
size_t	cwist_scheduler_pending_count (cwist_scheduler_t *s)
	Return the number of jobs waiting on the delayed-job heap.
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 with delayed execution.

The scheduler is built on top of cwist_io_queue. Worker threads run the queue's event loop, and a dedicated timer thread maintains a min-heap of delayed jobs. When a delayed deadline arrives, the timer thread submits the job to the io queue so a worker can execute it.

Definition in file scheduler.c.

Macro Definition Documentation

_POSIX_C_SOURCE

#define _POSIX_C_SOURCE   200809L

Definition at line 10 of file scheduler.c.

CWIST_SCHEDULER_HEAP_INIT

#define CWIST_SCHEDULER_HEAP_INIT   16

Definition at line 21 of file scheduler.c.

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.

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 worker and timer threads.

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 a scheduler and free all its resources.

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

)

Return the number of jobs waiting on the delayed-job heap.

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 delay.

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 for immediate execution by a worker thread.

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().