task_scheduler.h File Reference

#include <hawktracer/base_types.h>

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_TaskScheduler *	ht_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

enum 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_err

HT_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_scheduler

a 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_scheduler

a 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_scheduler	a pointer to the scheduler.
task_id	an 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_scheduler	a pointer to the scheduler.
mode	a task scheduling mode.

See also

HT_TaskSchedulingMode

Parameters

period	a minimum time (in nanoseconds) between two executions of the task.
callback	a task's function. Can not be NULL.
user_data	a 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_scheduler

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