ARGOBOTS  140a356fc09a44696eb3487150e459266f9b5405
Macros | Typedefs | Enumerations | Functions
Tool

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

Detailed Description

This group is for Tool.

Macro Definition Documentation

◆ ABT_TOOL_EVENT_THREAD_ALL

#define ABT_TOOL_EVENT_THREAD_ALL   ((uint64_t)((1 << 12) - 1))

Work-unit-event mask: all events above.

Definition at line 731 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_CANCEL

#define ABT_TOOL_EVENT_THREAD_CANCEL   (1 << 6)

Work-unit-event mask: canceling a work unit.

Definition at line 711 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_CREATE

#define ABT_TOOL_EVENT_THREAD_CREATE   (1 << 0)

Work-unit-event mask: creating a work unit.

Definition at line 681 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_FINISH

#define ABT_TOOL_EVENT_THREAD_FINISH   (1 << 5)

Work-unit-event mask: finishing a work unit.

Definition at line 706 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_FREE

#define ABT_TOOL_EVENT_THREAD_FREE   (1 << 2)

Work-unit-event mask: freeing a work unit.

Definition at line 691 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_JOIN

#define ABT_TOOL_EVENT_THREAD_JOIN   (1 << 1)

Work-unit-event mask: joining a work unit.

Definition at line 686 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_NONE

#define ABT_TOOL_EVENT_THREAD_NONE   (0)

Work-unit-event mask: none.

Definition at line 676 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_RESUME

#define ABT_TOOL_EVENT_THREAD_RESUME   (1 << 9)

Work-unit-event mask: resuming a work unit.

Definition at line 726 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_REVIVE

#define ABT_TOOL_EVENT_THREAD_REVIVE   (1 << 3)

Work-unit-event mask: reviving a work unit.

Definition at line 696 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_RUN

#define ABT_TOOL_EVENT_THREAD_RUN   (1 << 4)

Work-unit-event mask: running a work unit.

Definition at line 701 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_SUSPEND

#define ABT_TOOL_EVENT_THREAD_SUSPEND   (1 << 8)

Work-unit-event mask: suspending a work unit.

Definition at line 721 of file abt.h.

◆ ABT_TOOL_EVENT_THREAD_YIELD

#define ABT_TOOL_EVENT_THREAD_YIELD   (1 << 7)

Work-unit-event mask: yielding a work unit.

Definition at line 716 of file abt.h.

Typedef Documentation

◆ ABT_exec_entity_type

Execution entity type.

Definition at line 1010 of file abt.h.

◆ ABT_sync_event_type

Synchronization event type.

Definition at line 1015 of file abt.h.

◆ ABT_tool_context

typedef struct ABT_tool_context_opaque* ABT_tool_context

Tool context handle type.

A NULL handle of this type is ABT_TOOL_CONTEXT_NULL.

Definition at line 1000 of file abt.h.

◆ ABT_tool_query_kind

Tool query type.

Definition at line 1005 of file abt.h.

Enumeration Type Documentation

◆ ABT_exec_entity_type

Type of execution entity.

Enumerator
ABT_EXEC_ENTITY_TYPE_EXT 

External thread.

ABT_EXEC_ENTITY_TYPE_THREAD 

Work unit.

Definition at line 636 of file abt.h.

◆ ABT_sync_event_type

Type of synchronization event.

Enumerator
ABT_SYNC_EVENT_TYPE_UNKNOWN 

Unknown synchronization events.

ABT_SYNC_EVENT_TYPE_USER 

Explicit context switching triggered by the user.

ABT_SYNC_EVENT_TYPE_OTHER 

Other synchronization events.

ABT_SYNC_EVENT_TYPE_XSTREAM_JOIN 

Joining an executions stream.

ABT_SYNC_EVENT_TYPE_THREAD_JOIN 

Joining a work unit.

ABT_SYNC_EVENT_TYPE_MUTEX 

Events related to a mutex.

ABT_SYNC_EVENT_TYPE_COND 

Events related to a condition variable.

ABT_SYNC_EVENT_TYPE_RWLOCK 

Events related to a readers-writer lock.

ABT_SYNC_EVENT_TYPE_EVENTUAL 

Events related to an eventual.

ABT_SYNC_EVENT_TYPE_FUTURE 

Events related to a future.

ABT_SYNC_EVENT_TYPE_BARRIER 

Events related to a barrier.

Definition at line 647 of file abt.h.

◆ ABT_tool_query_kind

Tool query kind for ABT_tool_query_thread().

Enumerator
ABT_TOOL_QUERY_KIND_POOL 

Query a pool to which a work unit is or will be pushed.

ABT_TOOL_QUERY_KIND_STACK_DEPTH 

Query a current depth of stackable work units.

ABT_TOOL_QUERY_KIND_CALLER_TYPE 

Query a type of caller that incurs an event.

ABT_TOOL_QUERY_KIND_CALLER_HANDLE 

Query a handle to the caller that incurs an event.

ABT_TOOL_QUERY_KIND_SYNC_OBJECT_TYPE 

Query a type of synchronization object that incurs an event.

ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE 

Query a handle of the synchronization object that incurs an event.

Definition at line 617 of file abt.h.

Function Documentation

◆ 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().

Execution context
This routine can be called only in a callback function the tool callback function. This routine does not perform context switching the calling ULT unless any user-defined function that is involved in this routine performs context switching.
Errors
If this routine succeeds, ABT_SUCCESS is returned.
If query_kind is not a valid tool query kind for query, ABT_ERR_INV_ARG is returned.
If the tool feature is not supported, ABT_ERR_FEATURE_NA is returned.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If val is NULL, the results are undefined.
If the internal state of the Argobots is changed in the callback function, the results are undefined.
If context is a tool context that is not passed to the calling callback function, the results are undefined.
If context and event are not the same pair passed to the calling callback function, the results are undefined.
Parameters
[in]contexttool context handle
[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

Definition at line 222 of file tool.c.

◆ ABT_tool_register_thread_callback()

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:

  • The first argument: a work unit that triggers the event
  • The second argument: a handle of the underlying execution stream
  • The third argument: an event code (see ABT_TOOL_EVENT_THREAD)
  • The fourth argument: a tool context for ABT_tool_query_thread()
  • The fifth argument: 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.

Note
Invoking an event in 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.

Note
Even after 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().
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not perform context switching the calling ULT unless any user-defined function that is involved in this routine performs context switching.
Errors
If this routine succeeds, ABT_SUCCESS is returned.
If the tool feature is not supported, ABT_ERR_FEATURE_NA is returned.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If the tool context passed to cb_func() is accessed after cb_func() finishes, the results are undefined.
If the internal state of the Argobots is changed in cb_func(), the results are undefined.
Parameters
[in]cb_funccallback function pointer
[in]event_maskevent code mask
[in]user_arguser argument passed to cb_func
Returns
Error code

Definition at line 83 of file tool.c.