HawkTracer  0.8.0
task_scheduler.h File Reference

Go to the source code of this file.

Macros

#define HT_TASK_SCHEDULER_INVALID_TASK_ID   ((HT_TaskId)-1)
 An invalid task identifier. More...
 

Typedefs

typedef int32_t HT_TaskId
 A task scheduler's task identifier. More...
 
typedef struct _HT_TaskScheduler HT_TaskScheduler
 

Enumerations

enum  HT_TaskSchedulingMode { HT_TASK_SCHEDULING_IGNORE_DELAYS, HT_TASK_SCHEDULING_RESTART_TIMER }
 Task scheduling mode. More...
 

Functions

HT_API HT_TaskSchedulerht_task_scheduler_create (HT_ErrorCode *out_err)
 Creates an instance of the HT_TaskScheduler structure. More...
 
HT_API void ht_task_scheduler_destroy (HT_TaskScheduler *task_scheduler)
 Destroys task scheduler data structure. More...
 
HT_API HT_TaskId ht_task_scheduler_schedule_task (HT_TaskScheduler *task_scheduler, HT_TaskSchedulingMode mode, HT_DurationNs period, HT_TaskCallback callback, void *user_data)
 Adds a new task to a scheduler. More...
 
HT_API HT_Boolean ht_task_scheduler_remove_task (HT_TaskScheduler *task_scheduler, HT_TaskId task_id)
 Deletes a task from a scheduler. More...
 
HT_API void ht_task_scheduler_tick (HT_TaskScheduler *task_scheduler)
 Executes scheduled tasks when they time out. More...
 
HT_API HT_DurationNs ht_task_scheduler_get_optimal_tick_period (HT_TaskScheduler *task_scheduler)
 Gets optimal tick period for scheduled tasks. More...
 

Variables

HT_DECLS_BEGIN typedef HT_Boolean(* HT_TaskCallback )(void *user_data)
 A task scheduler's callback. More...
 

Macro Definition Documentation

◆ HT_TASK_SCHEDULER_INVALID_TASK_ID

#define HT_TASK_SCHEDULER_INVALID_TASK_ID   ((HT_TaskId)-1)

An invalid task identifier.

Typedef Documentation

◆ HT_TaskId

typedef int32_t HT_TaskId

A task scheduler's task identifier.

◆ HT_TaskScheduler

typedef struct _HT_TaskScheduler HT_TaskScheduler

Enumeration Type Documentation

◆ HT_TaskSchedulingMode

Task scheduling mode.

Enumerator
HT_TASK_SCHEDULING_IGNORE_DELAYS 

Ignores task execution delays; if the task has been run after the timeout, next task execution will be performed according to a schedule (so it won't be affected by a previous delay).

HT_TASK_SCHEDULING_RESTART_TIMER 

Takes delays into account, and restarts the timer for the task after its execution; if task was delayed, next task will be executed after a period time of the previous execution.

Function Documentation

◆ ht_task_scheduler_create()

HT_API HT_TaskScheduler* ht_task_scheduler_create ( HT_ErrorCode out_err)

Creates an instance of the HT_TaskScheduler structure.

Parameters
out_errHT_ERR_OK, if creation completed succesfully; otherwise, appropriate error code.
Returns
task_scheduler a pointer to the scheduler, or NULL if create failed.

◆ ht_task_scheduler_destroy()

HT_API void ht_task_scheduler_destroy ( HT_TaskScheduler task_scheduler)

Destroys task scheduler data structure.

Parameters
task_schedulera pointer to the scheduler.

◆ ht_task_scheduler_get_optimal_tick_period()

HT_API HT_DurationNs ht_task_scheduler_get_optimal_tick_period ( HT_TaskScheduler task_scheduler)

Gets optimal tick period for scheduled tasks.

The function returns the greatest common divisor of all task periods. E.g. for following periods of scheduled tasks: (10, 15, 25), optimal tick period is 5.

Note
This function ignores tasks with period equal to 0. Therefore optimal tick period for task periods: (10, 15, 25, 0) is still 5.
Parameters
task_schedulera pointer to the scheduler.
Returns
optimal tick period.

◆ ht_task_scheduler_remove_task()

HT_API HT_Boolean ht_task_scheduler_remove_task ( HT_TaskScheduler task_scheduler,
HT_TaskId  task_id 
)

Deletes a task from a scheduler.

Parameters
task_schedulera pointer to the scheduler.
task_idan identifier of the task to remove.
Returns
HT_TRUE, if task was removed successfully; if task doesn't exist, returns HT_FALSE.

◆ ht_task_scheduler_schedule_task()

HT_API HT_TaskId ht_task_scheduler_schedule_task ( HT_TaskScheduler task_scheduler,
HT_TaskSchedulingMode  mode,
HT_DurationNs  period,
HT_TaskCallback  callback,
void *  user_data 
)

Adds a new task to a scheduler.

Parameters
task_schedulera pointer to the scheduler.
modea task scheduling mode.
See also
HT_TaskSchedulingMode
Parameters
perioda minimum time (in nanoseconds) between two executions of the task.
callbacka task's function. Can not be NULL.
user_dataa pointer to a data which is passed to a callback when executed.
Returns
a unique identifier of the task if the task is scheduled successfully; otherwise HT_TASK_SCHEDULER_INVALID_TASK_ID.

◆ ht_task_scheduler_tick()

HT_API void ht_task_scheduler_tick ( HT_TaskScheduler task_scheduler)

Executes scheduled tasks when they time out.

Parameters
task_schedulera pointer to the scheduler.

Variable Documentation

◆ HT_TaskCallback

HT_DECLS_BEGIN typedef HT_Boolean(* HT_TaskCallback) (void *user_data)

A task scheduler's callback.

Returns
HT_TRUE if the task should be re-scheduled, or HT_FALSE if the task should be removed from scheduler after executing it.