ARGOBOTS  29b0d4cc91ca184a8278ddf690fd0bcb2119000e
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Functions
tool.c File Reference
#include "abti.h"
Include dependency graph for tool.c:

Go to the source code of this file.

Functions

static ABTU_ret_err int tool_query (ABTI_tool_context *p_tctx, ABT_tool_query_kind query_kind, void *val)
 
int ABT_tool_register_thread_callback (ABT_tool_thread_callback_fn cb_func, uint64_t event_mask_thread, void *user_arg)
 Register a callback function for ULT events. More...
 
int ABT_tool_register_task_callback (ABT_tool_task_callback_fn cb_func, uint64_t event_mask_task, void *user_arg)
 Register a callback function for tasklet events. More...
 
int ABT_tool_query_thread (ABT_tool_context context, uint64_t event_thread, ABT_tool_query_kind query_kind, void *val)
 Query information associated with a ULT event. More...
 
int ABT_tool_query_task (ABT_tool_context context, uint64_t event_task, ABT_tool_query_kind query_kind, void *val)
 Query information associated with a tasklet event. More...
 

Function Documentation

int ABT_tool_query_task ( ABT_tool_context  context,
uint64_t  event_task,
ABT_tool_query_kind  query_kind,
void *  val 
)

Query information associated with a tasklet event.

ABT_tool_query_task() returns information associated with the tasklet event via context. See ABT_tool_query_thread() for details.

Parameters
[in]contexthandle to the tool context
[in]event_tasktasklet event code passed to the callback function
[in]query_kindquery kind
[out]valpointer to storage where a returned value is saved
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_FEATURE_NAthe tool feature is not supported

Definition at line 225 of file tool.c.

int ABT_tool_query_thread ( ABT_tool_context  context,
uint64_t  event_thread,
ABT_tool_query_kind  query_kind,
void *  val 
)

Query information associated with a ULT event.

ABT_tool_query() returns information associated with the tool context context through val. Since context is valid only in the callback handler, this function must be called in the callback handler.

When query_kind is ABT_TOOL_QUERY_KIND_POOL, it sets *val to ABT_pool of a pool to which a work unit is or will be pushed. The query is valid when event is THREAD_CREATE, THREAD_REVIVE, THREAD_YIELD, THREAD_RESUME, TASK_CREATE, or TASK_REVIVE. Otherwise, *val is set to ABT_POOL_NULL.

When query_kind is ABT_TOOL_QUERY_KIND_STACK_DEPTH, it sets *val to the current depth of stackable work units as an int value while the level of the main scheduler is zero. For example, if the current thread is directly running on the main scheduler, the depth is 1. The query is valid when event is THREAD_RUN and TASK_RUN (the depth after the work unit runs), THREAD_FINISH and TASK_FINISH (the depth before the work unit finishes), THREAD_YIELD (the depth before the work unit yields), and THREAD_SUSPEND (the depth before the work unit suspends). Otherwise, *val is set to zero.

When query_kind is ABT_TOOL_QUERY_KIND_CALLER_TYPE, *val is set to ABT_exec_entity_type of an entity which incurs this event. The query is valid for all events.

When query_kind is ABT_TOOL_QUERY_KIND_CALLER_HANDLE, *val is set to a handle of an entity which incurs this event. Specifically, *val is set to a ULT handle (ABT_thread) if the caller type is ABT_EXEC_ENTITY_TYPE_THREAD. *val is set to a tasklet handle (ABT_task) if the caller type is ABT_EXEC_ENTITY_TYPE_TASK. If the caller is an external thread, *val is set to NULL. The query is valid for all events except for THREAD_CANCEL and TASK_CANCEL. Note that the caller is a previous work unit when event is THRAED_RUN or TASK_RUN.

When query_kind is ABT_TOOL_QUERY_KIND_SYNC_OBJECT_TYPE, *val is set to ABT_sync_event_type of an synchronization object which incurs this event. The synchronization object is returned when query_kind is ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE. Synchronization events, and ABT_sync_event_type, and synchronization objects are mapped as follows:

  • ABT_SYNC_EVENT_TYPE_USER: User's explicit call (e.g., ABT_thread_yield()) The synchronization object is not set ((void *)NULL).
  • ABT_SYNC_EVENT_TYPE_XSTREAM_JOIN: Waiting for completion of execution streams (e.g., ABT_xstream_join()) The synchronization object is an execution stream (ABT_xstream).
  • ABT_SYNC_EVENT_TYPE_THREAD_JOIN: Waiting for completion of ULTs (e.g., ABT_thread_join()) The synchronization object is a ULT (ABT_thread).
  • ABT_SYNC_EVENT_TYPE_TASK_JOIN: Waiting for completion of tasklets (e.g., ABT_task_join()) The synchronization object is a tasklet (ABT_task).
  • ABT_SYNC_EVENT_TYPE_MUTEX: Synchronization regarding a mutex (e.g., ABT_mutex_lock()) The synchronization object is a mutex (ABT_mutex).
  • ABT_SYNC_EVENT_TYPE_COND: Synchronization regarding a condition variable(e.g., ABT_cond_wait()) The synchronization object is a condition variable (ABT_cond).
  • ABT_SYNC_EVENT_TYPE_RWLOCK: Synchronization regarding a rwlock (e.g., ABT_rwlock_rdlock()) The synchronization object is a rwlock (ABT_rwlock).
  • ABT_SYNC_EVENT_TYPE_EVENTUAL: Synchronization regarding an eventual (e.g., ABT_eventual_wait()) The synchronization object is an eventual (ABT_eventual).
  • ABT_SYNC_EVENT_TYPE_FUTURE: Synchronization regarding a future (e.g., ABT_future_wait()) The synchronization object is a future (ABT_future).
  • ABT_SYNC_EVENT_TYPE_BARRIER: Synchronization regarding a barrier (e.g., ABT_barrier_wait()) The synchronization object is a barrier (ABT_barrier).
  • ABT_SYNC_EVENT_TYPE_OTHER: Unclassified synchronization (e.g., ABT_xstream_exit()) The synchronization object is not set ((void *)NULL).
  • ABT_SYNC_EVENT_TYPE_UNKNOWN event is neither THREAD_YIELD nor THREAD_SUSPEND. The synchronization object is not set ((void *)NULL). This query is valid for THREAD_YIELD and THREAD_SUSPEND.

An object to which a returned handle points to may be in an intermediate state, so users are discouraged not to read any internal state of such an object (e.g., by ABT_thread_get_state() or ABT_pool_get_size()).

Parameters
[in]contexthandle to the tool context
[in]eventevent code passed to the callback function
[in]query_kindquery kind
[out]valpointer to storage where a returned value is saved
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_FEATURE_NAthe tool feature is not supported

Definition at line 195 of file tool.c.

int ABT_tool_register_task_callback ( ABT_tool_task_callback_fn  cb_func,
uint64_t  event_mask_task,
void *  user_arg 
)

Register a callback function for tasklet events.

ABT_tool_register_task_callback() sets a callback function cb_func for tasklet events. Events that are not in event_mask are excluded. Users can stop the event callback by setting cb_func to zero.

cb_func is called with a target tasklet (the first argument), an underlying execution stream (the second argument), an event code (the third argument, see ABT_TOOL_EVENT_TASK), and the tool context that can be used for ABT_tool_query(). If the event occurs on an external thread, ABT_XSTREAM_NULL is passed. The returned tool context is only valid in the callback function.

An object to which a returned handle points to may be in an intermediate state, so users are discouraged not to read any internal state of such an object (e.g., by ABT_thread_get_state()).

Parameters
[in]cb_funccallback function pointer
[in]event_maskevent code mask
[in]user_arguser argument passed to cb_func
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_FEATURE_NAtool feature is not supported

Definition at line 87 of file tool.c.

int ABT_tool_register_thread_callback ( ABT_tool_thread_callback_fn  cb_func,
uint64_t  event_mask_thread,
void *  user_arg 
)

Register a callback function for ULT events.

ABT_tool_register_thread_callback() sets a callback function cb_func for ULT events. Events that are not in event_mask are excluded. Users can stop the event callback by setting cb_func to zero.

cb_func is called with a target thread (the first argument), an underlying execution stream (the second argument), an event code (the third argument, see ABT_TOOL_EVENT_THREAD), and the tool context that can be used for ABT_tool_query(). If the event occurs on an external thread, ABT_XSTREAM_NULL is passed. The returned tool context is only valid in the callback function.

An object to which a returned handle points to may be in an intermediate state, so users are discouraged not to read any internal state of such an object (e.g., by ABT_thread_get_state()).

Parameters
[in]cb_funccallback function pointer
[in]event_maskevent code mask
[in]user_arguser argument passed to cb_func
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_FEATURE_NAtool feature is not supported

Definition at line 44 of file tool.c.

static ABTU_ret_err int tool_query ( ABTI_tool_context *  p_tctx,
ABT_tool_query_kind  query_kind,
void *  val 
)
inlinestatic

Definition at line 245 of file tool.c.

Referenced by ABT_tool_query_task(), and ABT_tool_query_thread().