# `./fio-stl/102 queue.h` 28 public symbols. ### Macros #### `FIO_QUEUE_TASKS_PER_ALLOC` ```c #define FIO_QUEUE_TASKS_PER_ALLOC 338 ``` _Symbol type:_ `macro` #### `FIO_QUEUE_STATIC_INIT` ```c #define FIO_QUEUE_STATIC_INIT(queue) \ { \ .r = &(queue).mem, .w = &(queue).mem, \ .lock = (fio_thread_mutex_t)FIO_THREAD_MUTEX_INIT, \ .consumers = FIO_LIST_INIT((queue).consumers), \ } ``` May be used to initialize global, static memory, queues. _Symbol type:_ `macro` #### `FIO_TIMER_QUEUE_INIT` ```c #define FIO_TIMER_QUEUE_INIT \ { .lock = ((fio_thread_mutex_t)FIO_THREAD_MUTEX_INIT) } ``` _Symbol type:_ `macro` ### Types #### `fio_queue_task_s` ```c typedef struct { /** The function to call */ void (*fn)(void *, void *); /** User opaque data */ void *udata1; /** User opaque data */ void *udata2; } fio_queue_task_s ``` Task information _Symbol type:_ `type` #### `fio_queue_s` ```c typedef struct { /** task read pointer. */ fio___task_ring_s *r; /** task write pointer. */ fio___task_ring_s *w; /** the number of tasks waiting to be performed. */ uint32_t count; /** global queue lock. */ FIO___LOCK_TYPE lock; /** linked lists of consumer threads. */ FIO_LIST_NODE consumers; /** main ring buffer associated with the queue. */ fio___task_ring_s mem; } fio_queue_s ``` The queue object - should be considered opaque (or, at least, read only). _Symbol type:_ `type` #### `fio_timer_queue_s` ```c typedef struct { fio___timer_event_s *next; FIO___LOCK_TYPE lock; } fio_timer_queue_s ``` _Symbol type:_ `type` #### `fio_timer_schedule_args_s` ```c typedef struct { /** The timer function. If it returns a non-zero value, the timer stops. */ int (*fn)(void *, void *); /** Opaque user data. */ void *udata1; /** Opaque user data. */ void *udata2; /** Called when the timer is done (finished). */ void (*on_finish)(void *, void *); /** Timer interval, in milliseconds. */ uint32_t every; /** The number of times the timer should be performed. -1 == infinity. */ int32_t repetitions; /** Millisecond at which to start. If missing, filled automatically. */ int64_t start_at; } fio_timer_schedule_args_s ``` _Symbol type:_ `type` ### Functions #### `fio_queue_init` ```c inline void fio_queue_init(fio_queue_s *q) ``` Initializes a fio_queue_s object. _Symbol type:_ `function` #### `fio_queue_destroy` ```c void fio_queue_destroy(fio_queue_s *q) ``` Destroys a queue and re-initializes it, after freeing any used resources. _Symbol type:_ `function` #### `fio_queue_new` ```c fio_queue_s *fio_queue_new(void) ``` Creates a new queue object (allocated on the heap). _Symbol type:_ `function` #### `fio_queue_free` ```c void fio_queue_free(fio_queue_s *q) ``` Frees a queue object after calling fio_queue_destroy. _Symbol type:_ `function` #### `fio_queue_push` ```c int fio_queue_push(fio_queue_s *q, fio_queue_task_s task) ``` Pushes a task to the queue. Returns -1 on error. _Symbol type:_ `function` #### `fio_queue_push` ```c #define fio_queue_push(q, ...) \ fio_queue_push((q), (fio_queue_task_s){__VA_ARGS__}) ``` Pushes a task to the queue, offering named arguments for the task. Returns -1 on error. _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_queue_push_urgent` ```c int fio_queue_push_urgent(fio_queue_s *q, fio_queue_task_s task) ``` Pushes a task to the head of the queue. Returns -1 on error (no memory). _Symbol type:_ `function` #### `fio_queue_push_urgent` ```c #define fio_queue_push_urgent(q, ...) \ fio_queue_push_urgent((q), (fio_queue_task_s){__VA_ARGS__}) ``` Pushes a task to the queue, offering named arguments for the task. Returns -1 on error. _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_queue_pop` ```c fio_queue_task_s fio_queue_pop(fio_queue_s *q) ``` Pops a task from the queue (FIFO). Returns a NULL task on error. _Symbol type:_ `function` #### `fio_queue_perform` ```c int fio_queue_perform(fio_queue_s *q) ``` Performs a task from the queue. Returns -1 on error (queue empty). _Symbol type:_ `function` #### `fio_queue_perform_all` ```c void fio_queue_perform_all(fio_queue_s *q) ``` Performs all tasks in the queue. _Symbol type:_ `function` #### `fio_queue_count` ```c inline uint32_t fio_queue_count(fio_queue_s *q) ``` returns the number of tasks in the queue. _Symbol type:_ `function` #### `fio_queue_workers_add` ```c int fio_queue_workers_add(fio_queue_s *q, size_t count) ``` Adds worker / consumer threads to perform the jobs in the queue. _Symbol type:_ `function` #### `fio_queue_workers_stop` ```c void fio_queue_workers_stop(fio_queue_s *q) ``` Signals all worker threads to stop performing tasks and terminate. _Symbol type:_ `function` #### `fio_queue_workers_join` ```c void fio_queue_workers_join(fio_queue_s *q) ``` Signals all worker threads to stop, waiting for them to complete. _Symbol type:_ `function` #### `fio_queue_workers_wake` ```c void fio_queue_workers_wake(fio_queue_s *q) ``` Signals all worker threads to go back to work (new tasks added). _Symbol type:_ `function` #### `fio_timer_schedule` ```c void fio_timer_schedule(fio_timer_queue_s *timer_queue, fio_timer_schedule_args_s args) ``` Adds a time-bound event to the timer queue. _Symbol type:_ `function` #### `fio_timer_schedule` ```c #define fio_timer_schedule(timer_queue, ...) \ fio_timer_schedule((timer_queue), (fio_timer_schedule_args_s){__VA_ARGS__}) ``` A MACRO allowing named arguments to be used. See fio_timer_schedule_args_s. _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_timer_push2queue` ```c size_t fio_timer_push2queue(fio_queue_s *queue, fio_timer_queue_s *timer_queue, int64_t now_in_milliseconds) ``` Pushes due events from the timer queue to an event queue. _Symbol type:_ `function` #### `fio_timer_next_at` ```c inline int64_t fio_timer_next_at(fio_timer_queue_s *timer_queue) ``` _Symbol type:_ `function` #### `fio_timer_destroy` ```c void fio_timer_destroy(fio_timer_queue_s *timer_queue) ``` Clears any waiting timer bound tasks. NOTE: The timer queue must NEVER be freed when there's a chance that timer tasks are waiting to be performed in a `fio_queue_s`. This is due to the fact that the tasks may try to reschedule themselves (if they repeat). _Symbol type:_ `function` -----------------------------------------------------