ARGOBOTS
140a356fc09a44696eb3487150e459266f9b5405
|
This group is for Tool. More...
Macros | |
#define | ABT_TOOL_EVENT_THREAD_NONE (0) |
Work-unit-event mask: none. More... | |
#define | ABT_TOOL_EVENT_THREAD_CREATE (1 << 0) |
Work-unit-event mask: creating a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_JOIN (1 << 1) |
Work-unit-event mask: joining a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_FREE (1 << 2) |
Work-unit-event mask: freeing a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_REVIVE (1 << 3) |
Work-unit-event mask: reviving a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_RUN (1 << 4) |
Work-unit-event mask: running a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_FINISH (1 << 5) |
Work-unit-event mask: finishing a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_CANCEL (1 << 6) |
Work-unit-event mask: canceling a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_YIELD (1 << 7) |
Work-unit-event mask: yielding a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_SUSPEND (1 << 8) |
Work-unit-event mask: suspending a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_RESUME (1 << 9) |
Work-unit-event mask: resuming a work unit. More... | |
#define | ABT_TOOL_EVENT_THREAD_ALL ((uint64_t)((1 << 12) - 1)) |
Work-unit-event mask: all events above. More... | |
Typedefs | |
typedef struct ABT_tool_context_opaque * | ABT_tool_context |
Tool context handle type. More... | |
typedef enum ABT_tool_query_kind | ABT_tool_query_kind |
Tool query type. More... | |
typedef enum ABT_exec_entity_type | ABT_exec_entity_type |
Execution entity type. More... | |
typedef enum ABT_sync_event_type | ABT_sync_event_type |
Synchronization event type. More... | |
Enumerations | |
enum | ABT_tool_query_kind { ABT_TOOL_QUERY_KIND_POOL, ABT_TOOL_QUERY_KIND_STACK_DEPTH, ABT_TOOL_QUERY_KIND_CALLER_TYPE, ABT_TOOL_QUERY_KIND_CALLER_HANDLE, ABT_TOOL_QUERY_KIND_SYNC_OBJECT_TYPE, ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE } |
Tool query kind for ABT_tool_query_thread() . More... | |
enum | ABT_exec_entity_type { ABT_EXEC_ENTITY_TYPE_EXT, ABT_EXEC_ENTITY_TYPE_THREAD } |
Type of execution entity. More... | |
enum | ABT_sync_event_type { ABT_SYNC_EVENT_TYPE_UNKNOWN = 0, ABT_SYNC_EVENT_TYPE_USER, ABT_SYNC_EVENT_TYPE_OTHER, ABT_SYNC_EVENT_TYPE_XSTREAM_JOIN, ABT_SYNC_EVENT_TYPE_THREAD_JOIN, ABT_SYNC_EVENT_TYPE_MUTEX, ABT_SYNC_EVENT_TYPE_COND, ABT_SYNC_EVENT_TYPE_RWLOCK, ABT_SYNC_EVENT_TYPE_EVENTUAL, ABT_SYNC_EVENT_TYPE_FUTURE, ABT_SYNC_EVENT_TYPE_BARRIER } |
Type of synchronization event. More... | |
Functions | |
int | ABT_tool_register_thread_callback (ABT_tool_thread_callback_fn cb_func, uint64_t event_mask, void *user_arg) |
Register a callback function for work unit events. More... | |
int | ABT_tool_query_thread (ABT_tool_context context, uint64_t event, ABT_tool_query_kind query_kind, void *val) |
Query information associated with a work unit event. More... | |
This group is for Tool.
#define ABT_TOOL_EVENT_THREAD_ALL ((uint64_t)((1 << 12) - 1)) |
#define ABT_TOOL_EVENT_THREAD_CANCEL (1 << 6) |
#define ABT_TOOL_EVENT_THREAD_CREATE (1 << 0) |
#define ABT_TOOL_EVENT_THREAD_FINISH (1 << 5) |
#define ABT_TOOL_EVENT_THREAD_FREE (1 << 2) |
#define ABT_TOOL_EVENT_THREAD_JOIN (1 << 1) |
#define ABT_TOOL_EVENT_THREAD_NONE (0) |
#define ABT_TOOL_EVENT_THREAD_RESUME (1 << 9) |
#define ABT_TOOL_EVENT_THREAD_REVIVE (1 << 3) |
#define ABT_TOOL_EVENT_THREAD_RUN (1 << 4) |
#define ABT_TOOL_EVENT_THREAD_SUSPEND (1 << 8) |
#define ABT_TOOL_EVENT_THREAD_YIELD (1 << 7) |
typedef enum ABT_exec_entity_type ABT_exec_entity_type |
typedef enum ABT_sync_event_type ABT_sync_event_type |
typedef struct ABT_tool_context_opaque* ABT_tool_context |
typedef enum ABT_tool_query_kind ABT_tool_query_kind |
enum ABT_exec_entity_type |
enum ABT_sync_event_type |
Type of synchronization event.
enum ABT_tool_query_kind |
Tool query kind for ABT_tool_query_thread()
.
int ABT_tool_query_thread | ( | ABT_tool_context | context, |
uint64_t | event, | ||
ABT_tool_query_kind | query_kind, | ||
void * | val | ||
) |
Query information associated with a work unit event.
ABT_tool_query_thread()
returns information associated with the tool context context
through val
. Because context
is valid only in the callback function, this function must be called in the callback function.
When query_kind
is ABT_TOOL_QUERY_KIND_POOL
, this routine 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
.
When query_kind
is ABT_TOOL_QUERY_KIND_STACK_DEPTH
, this routine sets val
to the current depth of stackable work units as an int
value while the level of the work unit associated with the main scheduler is zero. For example, if the current thread is running directly on the main scheduler, the depth is 1. The query is valid when event
is THREAD_RUN
(the depth after the work unit runs), THREAD_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).
When query_kind
is ABT_TOOL_QUERY_KIND_CALLER_TYPE
, this routine sets val
to ABT_exec_entity_type
of an entity that incurs this event. The query is valid for all events.
When query_kind
is ABT_TOOL_QUERY_KIND_CALLER_HANDLE
, this routine sets val
to a handle of an entity that incurs this event. Specifically, this routine sets val
to a work unit handle (ABT_thread
) if the caller type is ABT_EXEC_ENTITY_TYPE_THREAD
. If the caller is an external thread, this routine sets val
to NULL
. The query is valid for all events except for THREAD_CANCEL
. Note that the caller is a previous work unit running on the same execution stream when event
is THRAED_RUN
.
When query_kind
is ABT_TOOL_QUERY_KIND_SYNC_OBJECT_TYPE
, this routine sets val
to ABT_sync_event_type
of an synchronization object that incurs this event. The synchronization object is returned when query_kind
is ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE
. This query is valid for THREAD_YIELD
and THREAD_SUSPEND
.
Synchronization events, ABT_sync_event_type
, and synchronization objects are mapped as follows:
ABT_SYNC_EVENT_TYPE_USER:
The user's explicit call (e.g., ABT_thread_yield()
). The synchronization object is none, so NULL
is set to val
if ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE
is passed.
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 a work unit (e.g., ABT_thread_join()
or ABT_task_join()
). The synchronization object is a work unit (ABT_thread
).
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 readers-writer lock (e.g., ABT_rwlock_rdlock()
). The synchronization object is a readers-writer lock (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 none, so NULL
is set to val
if ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE
is passed.
An object referenced by the returned handle (e.g., the work unit handle) may be in an intermediate state, so users are recommended not to read any internal state of such an object (e.g., by ABT_task_get_state()
) in cb_func()
.
ABT_SUCCESS
is returned.query_kind
is not a valid tool query kind for query
, ABT_ERR_INV_ARG
is returned.ABT_ERR_FEATURE_NA
is returned.val
is NULL
, the results are undefined.context
is a tool context that is not passed to the calling callback function, the results are undefined.context
and event
are not the same pair passed to the calling callback function, the results are undefined.[in] | context | tool context handle |
[in] | event | event code passed to the callback function |
[in] | query_kind | query kind |
[out] | val | pointer to storage where a returned value is saved |
int ABT_tool_register_thread_callback | ( | ABT_tool_thread_callback_fn | cb_func, |
uint64_t | event_mask, | ||
void * | user_arg | ||
) |
Register a callback function for work unit events.
ABT_tool_register_thread_callback()
sets the callback function cb_func()
for work unit events. The events are enabled if event_mask
have their corresponding bits. The other events are disabled. Users can stop the event callback by setting cb_func
to NULL
.
cb_func()
is called with the following arguments:
ABT_TOOL_EVENT_THREAD
)ABT_tool_query_thread()
user_arg
passed to this routine.If the event occurs on an external thread, ABT_XSTREAM_NULL
is passed as the second argument. The returned tool context is valid only before the callback function finishes.
An object referenced by the returned handle (e.g., a work unit handle) may be in an intermediate state, so users are discouraged to read any internal state of such an object (e.g., by ABT_thread_get_state()
) in cb_func()
. Instead, the user should use ABT_tool_query_thread()
. The caller of cb_func()
might be neither a work unit that triggers the event nor a work unit that is running on the same execution stream. A program that relies on the caller of cb_func()
is non-conforming.
This routine can be called while other work unit events are happening. This routine atomically sets cb_func()
, event_mask
, and user_arg
at the same time.
cb_func()
may cause an infinite invocation of cb_func()
. It is the user's responsibility to take a proper measure to avoid it.A combination of a callback function, an event mask its argument for a tool interface is updated atomically.
ABT_tool_register_thread_callback()
returns, another event call might be still in the previous cb_func()
and using the previous user_arg
. Argobots does not provide a method to guarantee that the previous cb_func
and user_arg
get unused. Hence, the user needs to carefully maintain consistency before and after ABT_tool_register_thread_callback()
.ABT_SUCCESS
is returned.ABT_ERR_FEATURE_NA
is returned.cb_func()
is accessed after cb_func()
finishes, the results are undefined.cb_func()
, the results are undefined.[in] | cb_func | callback function pointer |
[in] | event_mask | event code mask |
[in] | user_arg | user argument passed to cb_func |