DAOS API: src/include/daos/tse.h File Reference

| DAOS API (v2.1 - dev)

Loading...
Searching...
No Matches
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)
int | tse_task_register_comp_cb_and_reinit (tse_task_t *task, tse_task_cb_t comp_cb, void *arg, size_t arg_size, uint64_t delay)
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 26 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 24 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 28 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 57 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 62 of file tse.h.

## ◆ tse_task_func_t

typedef int(* tse_task_func_t) (tse_task_t *)

A task callback function

Definition at line 59 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_comp_cb_and_reinit()

int tse_task_register_comp_cb_and_reinit | ( | tse_task_t * | task,
|  | tse_task_cb_t | comp_cb,
|  | void * | arg,
|  | size_t | arg_size,
|  | uint64_t | delay )

Atomically register a completion callback and reinitialize the task for retry with an optional scheduling delay. If the reinitialization fails the newly registered callback is removed and freed so the caller never leaks a dangling tse_task_cb node.

Parameters

  [in] | task | Task to reinitialize for retry
  [in] | comp_cb | Completion callback to register for the retried run
  [in] | arg | Callback argument (copied internally, like tse_task_register_comp_cb)
  [in] | arg_size | Size of the argument
  [in] | delay | Scheduling delay in microseconds (0 = immediate)

Returns
  0 on success, negative errno on failure.

## ◆ 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.