tse.h File Reference

#include <gurt/list.h>
#include <pthread.h>
#include <inttypes.h>
#include <stdbool.h>

Go to the source code of this file.

Data Structures
struct	tse_task
struct	tse_sched_t

Macros
#define	TSE_TASK_ARG_LEN   (840 + sizeof(pthread_mutex_t))
#define	TSE_PRIV_SIZE   (TSE_TASK_ARG_LEN + 136)
#define	TSE_TASK_SIZE   (TSE_PRIV_SIZE + 8)

Typedefs
typedef struct tse_task	tse_task_t
typedef int(*	tse_sched_comp_cb_t) (void *args, int rc)
typedef int(*	tse_task_func_t) (tse_task_t *)
typedef int(*	tse_task_cb_t) (tse_task_t *, void *arg)

Functions
void *	tse_task2arg (tse_task_t *task)
tse_sched_t *	tse_task2sched (tse_task_t *task)
int	tse_sched_init (tse_sched_t *sched, tse_sched_comp_cb_t comp_cb, void *udata)
void	tse_sched_fini (tse_sched_t *sched)
void	tse_sched_addref (tse_sched_t *sched)
void	tse_sched_decref (tse_sched_t *sched)
void	tse_sched_complete (tse_sched_t *sched, int ret, bool cancel)
int	tse_sched_register_comp_cb (tse_sched_t *sched, tse_sched_comp_cb_t comp_cb, void *arg)
void	tse_sched_progress (tse_sched_t *sched)
bool	tse_sched_check_complete (tse_sched_t *sched)
int	tse_task_create (tse_task_func_t task_func, tse_sched_t *sched, void *priv, tse_task_t **taskp)
int	tse_task_schedule (tse_task_t *task, bool instant)
int	tse_task_schedule_with_delay (tse_task_t *task, bool instant, uint64_t delay)
int	tse_task_register_comp_cb (tse_task_t *task, tse_task_cb_t comp_cb, void *arg, size_t arg_size)
void	tse_task_complete (tse_task_t *task, int ret)
void *	tse_task_buf_embedded (tse_task_t *task, int size)
void *	tse_task_get_priv (tse_task_t *task)
void *	tse_task_set_priv (tse_task_t *task, void *priv)
int	tse_task_register_deps (tse_task_t *task, int num_deps, tse_task_t *dep_tasks[])
int	tse_task_register_cbs (tse_task_t *task, tse_task_cb_t prep_cb, void *prep_data, size_t prep_data_size, tse_task_cb_t comp_cb, void *comp_data, size_t comp_data_size)
int	tse_task_reinit (tse_task_t *task)
int	tse_task_reinit_with_delay (tse_task_t *task, uint64_t delay)
int	tse_task_reset (tse_task_t *task, tse_task_func_t task_func, void *priv)
void	tse_task_addref (tse_task_t *task)
void	tse_task_decref (tse_task_t *task)
int	tse_task_list_add (tse_task_t *task, d_list_t *head)
void	tse_task_list_del (tse_task_t *task)
tse_task_t *	tse_task_list_first (d_list_t *head)
void	tse_task_list_sched (d_list_t *head, bool instant)
void	tse_task_list_abort (d_list_t *head, int rc)
int	tse_task_list_depend (d_list_t *head, tse_task_t *task)
int	tse_task_depend_list (tse_task_t *task, d_list_t *head)
int	tse_task_list_traverse (d_list_t *head, tse_task_cb_t cb, void *arg)
int	tse_task_list_traverse_adv (d_list_t *head, tse_task_cb_t cb, void *arg)
void	tse_disable_propagate (tse_task_t *task)

Detailed Description

Task Execution Engine: Generic scheduler for creating tasks and dependencies between them.

Definition in file tse.h.

Macro Definition Documentation

TSE_PRIV_SIZE

#define TSE_PRIV_SIZE   (TSE_TASK_ARG_LEN + 136)

internal tse private data size (struct tse_task_private)

Definition at line 25 of file tse.h.

TSE_TASK_ARG_LEN

#define TSE_TASK_ARG_LEN   (840 + sizeof(pthread_mutex_t))

tse_task arguments max length (pthread_mutex_t is of different size between x86 and aarch64).

Definition at line 23 of file tse.h.

TSE_TASK_SIZE

#define TSE_TASK_SIZE   (TSE_PRIV_SIZE + 8)

tse_task is used to track single asynchronous operation (8 bytes used for public members).

Definition at line 27 of file tse.h.

Typedef Documentation

tse_sched_comp_cb_t

typedef int(* tse_sched_comp_cb_t) (void *args, int rc)

Callback function for when all tasks in scheduler are complete

Definition at line 56 of file tse.h.

tse_task_cb_t

typedef int(* tse_task_cb_t) (tse_task_t *, void *arg)

CB type for prepare, completion, and result processing

Definition at line 61 of file tse.h.

tse_task_func_t

typedef int(* tse_task_func_t) (tse_task_t *)

A task callback function

Definition at line 58 of file tse.h.

tse_task_t

typedef struct tse_task tse_task_t

struct for a task object that is used for tracking an operation

Function Documentation

tse_disable_propagate()

void tse_disable_propagate

(

tse_task_t *

task

)

Set the task don't propagate err-code from dependent tasks.

tse_sched_addref()

void tse_sched_addref

(

tse_sched_t *

sched

)

Take reference of the scheduler.

Parameters

[in]

sched

the scheduler pointer.

tse_sched_check_complete()

bool tse_sched_check_complete

(

tse_sched_t *

sched

)

Check completion on all tasks in the scheduler.

Parameters

[in]

sched

Schedule to check.

Returns

true if scheduler is empty, false otherwise.

tse_sched_complete()

void tse_sched_complete	(	tse_sched_t *	sched,
		int	ret,
		bool	cancel )

Wait for all tasks in the scheduler to complete and finalize it. If another thread is completing the scheduler, this returns immediately.

Parameters

[in]	sched	scheduler to be completed.
[in]	ret	result for scheduler completion.
[in]	cancel	cancel all tasks in scheduler if true.

tse_sched_decref()

void tse_sched_decref

(

tse_sched_t *

sched

)

Release reference of the scheduler.

Parameters

[in]

sched

the scheduler pointer.

tse_sched_fini()

void tse_sched_fini

(

tse_sched_t *

sched

)

Finish the scheduler.

Parameters

[in]

sched

the scheduler to be finished.

tse_sched_init()

int tse_sched_init	(	tse_sched_t *	sched,
		tse_sched_comp_cb_t	comp_cb,
		void *	udata )

Initialize the scheduler with an optional completion callback and pointer to user data. Caller is responsible to complete or cancel the scheduler.

Parameters

[in]	sched	scheduler to be initialized.
[in]	comp_cb	Optional callback to be called when scheduler is done.
[in]	udata	Optional pointer to user data to associate with the scheduler. This is stored in ds_udata in the scheduler struct and passed in to comp_cb as the argument when the callback is invoked.

Returns

0 if initialization succeeds.

negative errno if initialization fails.

tse_sched_progress()

void tse_sched_progress

(

tse_sched_t *

sched

)

Make progress on scheduler. Runs tasks that are ready to be executed after the tasks they depend on were completed. Note that task completion using tse_task_complete() must be done by the engine user to push progress on the engine. In DAOS tse_task_complete is called by the completion CB of the RPC request that is sent to the server.

Parameters

[in]

sched

Scheduler to make progress on.

tse_sched_register_comp_cb()

int tse_sched_register_comp_cb	(	tse_sched_t *	sched,
		tse_sched_comp_cb_t	comp_cb,
		void *	arg )

register complete callback for scheduler.

Parameters

[in]	sched	scheduler where to register the completion callback.
[in]	comp_cb	completion callback to be registered.
[in]	arg	argument of the completion callback.

Returns

0 if registration succeeds.

errno if registration fails.

tse_task2arg()

void * tse_task2arg

(

tse_task_t *

task

)

Convert from task to arg

tse_task2sched()

tse_sched_t * tse_task2sched

(

tse_task_t *

task

)

Return scheduler task is associated with

tse_task_addref()

void tse_task_addref

(

tse_task_t *

task

)

Take reference on the task

tse_task_buf_embedded()

void * tse_task_buf_embedded	(	tse_task_t *	task,
		int	size )

Get embedded buffer of a task, user can use it to carry function parameters. Embedded buffer of task has size limit, this function will return NULL if buf_size is larger than the limit.

User should use private data by tse_task_set_priv() to pass large parameter.

Parameters

[in]	task	task to get the buffer.
[in]	size	task buffer size.

Returns

pointer to the buffer.

tse_task_complete()

void tse_task_complete	(	tse_task_t *	task,
		int	ret )

Mark task as completed.

Parameters

[in]	task	task to be completed.
[in]	ret	ret result of the task.

tse_task_create()

int tse_task_create	(	tse_task_func_t	task_func,
		tse_sched_t *	sched,
		void *	priv,
		tse_task_t **	taskp )

Initialize the tse_task.

The task will be added to the scheduler task list, and being scheduled later, if dependent task is provided, then the task will be added to the dep list of the dependent task, once the dependent task is done, then the task will be added to the scheduler list.

Parameters

[in]	task_func	the function to be executed when the task is executed.
[in]	sched	daos scheduler where the daos task will be attached to.
[in]	priv	private data passed into the task, user can get it by calling tse_task_get_priv, or rewrite by calling tse_task_set_priv.
[out]	taskp	pointer to tse_task to be allocated and initialized. The task is freed internally when complete is called.

Returns

0 if initialization succeeds.

negative errno if it fails.

tse_task_decref()

void tse_task_decref

(

tse_task_t *

task

)

Drop reference on the task

tse_task_depend_list()

int tse_task_depend_list	(	tse_task_t *	task,
		d_list_t *	head )

task depends on all tasks attached on list head

tse_task_get_priv()

void * tse_task_get_priv

(

tse_task_t *

task

)

Return the private data of the task. Private data can be set while creating task, or by calling tse_task_set_priv.

tse_task_list_abort()

void tse_task_list_abort	(	d_list_t *	head,
		int	rc )

Abort all tasks attached on list head.

tse_task_list_add()

int tse_task_list_add	(	tse_task_t *	task,
		d_list_t *	head )

Add a newly created task to a list. It returns error if the task is already running or completed.

tse_task_list_del()

void tse_task_list_del

(

tse_task_t *

task

)

Remove the task from list head.

tse_task_list_depend()

int tse_task_list_depend	(	d_list_t *	head,
		tse_task_t *	task )

All tasks attached on head depend on list task.

tse_task_list_first()

tse_task_t * tse_task_list_first

(

d_list_t *

head

)

The first task linked on list head, it returns NULL if the list is empty.

tse_task_list_sched()

void tse_task_list_sched	(	d_list_t *	head,
		bool	instant )

Schedule all tasks attached on list head.

tse_task_list_traverse()

int tse_task_list_traverse	(	d_list_t *	head,
		tse_task_cb_t	cb,
		void *	arg )

Traverse all tasks on list head, invoke the cb with parameter of arg on each task. User is free to remove the task from the list head within the cb's executing.

tse_task_list_traverse_adv()

int tse_task_list_traverse_adv	(	d_list_t *	head,
		tse_task_cb_t	cb,
		void *	arg )

Advanced tse_task_list_traverse, the task's dtp_task_list or head list possibly be changed/zeroed after cb executed.

tse_task_register_cbs()

int tse_task_register_cbs	(	tse_task_t *	task,
		tse_task_cb_t	prep_cb,
		void *	prep_data,
		size_t	prep_data_size,
		tse_task_cb_t	comp_cb,
		void *	comp_data,
		size_t	comp_data_size )

Register prepare and completion callbacks that will be executed right before the task is scheduled and after it completes respectively.

Parameters

[in]	task	Task to add CBs on.
[in]	prep_cb	Prepare callback.
[in]	prep_data_size	Size of the user provided prep data to be copied internally.
[in]	prep_data	User data passed to the prepare callback.
[in]	comp_cb	Completion callback
[in]	comp_data_size	Size of the user provided comp data to be copied internally.
[in]	comp_data	User data passed to the completion callback.

Returns

0 if success. negative errno if it fails.

tse_task_register_comp_cb()

int tse_task_register_comp_cb	(	tse_task_t *	task,
		tse_task_cb_t	comp_cb,
		void *	arg,
		size_t	arg_size )

register complete callback for the task.

Parameters

[in]	task	task to be registered complete callback.
[in]	comp_cb	complete callback.
[in]	arg	callback argument.
[in]	arg_size	size of the argument.

Returns

0 if register succeeds.

negative errno if it fails.

tse_task_register_deps()

int tse_task_register_deps	(	tse_task_t *	task,
		int	num_deps,
		tse_task_t *	dep_tasks[] )

Register dependency tasks that will be required to be completed before the the task can be scheduled. The dependency tasks cannot be in progress.

Parameters

[in]	task	Task to add dependencies for.
[in]	num_deps	Number of tasks in the task array.
[in]	dep_tasks	Task array for all the tasks that are required to complete before the task can scheduled.

Returns

0 if success. negative errno if it fails.

tse_task_reinit()

int tse_task_reinit

(

tse_task_t *

task

)

Reinitialize a task and move it into the scheduler's initialize list. The task must have a body function to be reinserted into the scheduler. Once the task being reinitialized, it possible be executed by other thread when it progresses the scheduler. So all accesses to the task must happen before the reinit call, for example task dependency/callback registration or task argument accessing.

Parameters

[in]

task

Task to reinitialize

Returns

0 if success. negative errno if it fails.

tse_task_reinit_with_delay()

int tse_task_reinit_with_delay	(	tse_task_t *	task,
		uint64_t	delay )

Same as tse_task_reinit, except that task will not be re-executed within delay microseconds.

Parameters

[in]	task	Task to reinitialize
[in]	delay	Scheduling delay in microseconds

Returns

0 if success. negative errno if it fails.

tse_task_reset()

int tse_task_reset	(	tse_task_t *	task,
		tse_task_func_t	task_func,
		void *	priv )

Reset a task with a new body function. The task must have already completed or not started yet, and must have a > 0 valid ref count (not freed). This allows a user to reuse a task with a different body function and not have to recreate a task for a different operation.

Parameters

[in]	task	Task to reset
[in]	task_func	the function to be executed when the task is executed.
[in]	priv	private data passed into the task

Returns

0 if success. negative errno if it fails.

tse_task_schedule()

int tse_task_schedule	(	tse_task_t *	task,
		bool	instant )

Add task to scheduler it was initialized with. If task body function should be called immediately as part of this function, instant should be set to true; otherwise if false task would be in the scheduler init list and progressed when the scheduler is progressed.

Parameters

[in]	task	task to be scheduled.
[in]	instant	flag to indicate whether task should be executed immediately.

Returns

0 if success negative errno if fail.

tse_task_schedule_with_delay()

int tse_task_schedule_with_delay	(	tse_task_t *	task,
		bool	instant,
		uint64_t	delay )

Same as tse_task_schedule, expect that task will not be executed within delay microseconds if instant is false.

Parameters

[in]	task	task to be scheduled.
[in]	instant	flag to indicate whether task should be executed immediately.
[in]	delay	scheduling delay in microseconds.

Returns

0 if success negative errno if fail.

tse_task_set_priv()

void * tse_task_set_priv	(	tse_task_t *	task,
		void *	priv )

Set or change the private data of the task. The original private data will be returned.