ARGOBOTS  4dc37e16e1b227a480715ab67dae1dcfb4d2d4e0
Macros | Typedefs | Enumerations | Functions
Information

This group is for getting runtime information of Argobots. The routines in this group are meant for debugging and diagnosing Argobots. More...

Macros

#define ABT_VERSION   "1.1"
 Version string of Argobots. More...
 
#define ABT_NUMVERSION   10100300
 Version number of Argobots. More...
 

Typedefs

typedef enum ABT_info_query_kind ABT_info_query_kind
 Query type for ABT_info_query_config(). More...
 

Enumerations

enum  ABT_info_query_kind {
  ABT_INFO_QUERY_KIND_ENABLED_DEBUG, ABT_INFO_QUERY_KIND_ENABLED_PRINT_ERRNO, ABT_INFO_QUERY_KIND_ENABLED_LOG, ABT_INFO_QUERY_KIND_ENABLED_VALGRIND,
  ABT_INFO_QUERY_KIND_ENABLED_CHECK_ERROR, ABT_INFO_QUERY_KIND_ENABLED_CHECK_POOL_PRODUCER, ABT_INFO_QUERY_KIND_ENABLED_CHECK_POOL_CONSUMER, ABT_INFO_QUERY_KIND_ENABLED_PRESERVE_FPU,
  ABT_INFO_QUERY_KIND_ENABLED_THREAD_CANCEL, ABT_INFO_QUERY_KIND_ENABLED_TASK_CANCEL, ABT_INFO_QUERY_KIND_ENABLED_MIGRATION, ABT_INFO_QUERY_KIND_ENABLED_STACKABLE_SCHED,
  ABT_INFO_QUERY_KIND_ENABLED_EXTERNAL_THREAD, ABT_INFO_QUERY_KIND_ENABLED_SCHED_SLEEP, ABT_INFO_QUERY_KIND_ENABLED_PRINT_CONFIG, ABT_INFO_QUERY_KIND_ENABLED_AFFINITY,
  ABT_INFO_QUERY_KIND_MAX_NUM_XSTREAMS, ABT_INFO_QUERY_KIND_DEFAULT_THREAD_STACKSIZE, ABT_INFO_QUERY_KIND_DEFAULT_SCHED_STACKSIZE, ABT_INFO_QUERY_KIND_DEFAULT_SCHED_EVENT_FREQ,
  ABT_INFO_QUERY_KIND_DEFAULT_SCHED_SLEEP_NSEC, ABT_INFO_QUERY_KIND_ENABLED_TOOL, ABT_INFO_QUERY_KIND_FCONTEXT, ABT_INFO_QUERY_KIND_DYNAMIC_PROMOTION,
  ABT_INFO_QUERY_KIND_ENABLED_STACK_UNWIND, ABT_INFO_QUERY_KIND_ENABLED_STACK_OVERFLOW_CHECK, ABT_INFO_QUERY_KIND_WAIT_POLICY, ABT_INFO_QUERY_KIND_ENABLED_LAZY_STACK_ALLOC
}
 Query kind for ABT_info_query_config(). More...
 

Functions

int ABT_info_query_config (ABT_info_query_kind query_kind, void *val)
 Retrieve the configuration information. More...
 
int ABT_info_print_config (FILE *fp)
 Print the runtime information of Argobots. More...
 
int ABT_info_print_all_xstreams (FILE *fp)
 Print the information of all execution streams. More...
 
int ABT_info_print_xstream (FILE *fp, ABT_xstream xstream)
 Print the information of an execution stream. More...
 
int ABT_info_print_sched (FILE *fp, ABT_sched sched)
 Print the information of a scheduler. More...
 
int ABT_info_print_pool (FILE *fp, ABT_pool pool)
 Print the information of a pool. More...
 
int ABT_info_print_thread (FILE *fp, ABT_thread thread)
 Print the information of a work unit. More...
 
int ABT_info_print_thread_attr (FILE *fp, ABT_thread_attr attr)
 Print the information of a ULT attribute. More...
 
int ABT_info_print_task (FILE *fp, ABT_task task)
 Print the information of a work unit. More...
 
int ABT_info_print_thread_stack (FILE *fp, ABT_thread thread)
 Print stack of a work unit. More...
 
int ABT_info_print_thread_stacks_in_pool (FILE *fp, ABT_pool pool)
 Print stacks of all work units in a pool. More...
 
int ABT_info_trigger_print_all_thread_stacks (FILE *fp, double timeout, void(*cb_func)(ABT_bool, void *), void *arg)
 Print stacks of work units in pools associated with all the main schedulers. More...
 

Detailed Description

This group is for getting runtime information of Argobots. The routines in this group are meant for debugging and diagnosing Argobots.

Macro Definition Documentation

◆ ABT_NUMVERSION

#define ABT_NUMVERSION   10100300

Version number of Argobots.

ABT_NUMVERSION is the numeric version of Argobots that can be used in numeric comparisons. ABT_NUMVERSION is calculated as follows.

ABT_NUMVERSION = [MAJ] * 10000000 + [MIN] * 100000 + [REV] * 1000
+ [EXT] * 100 + [EXT_NUMBER]
where [EXT] is converted to the following format number:
ALPHA (a) = 0 (ABT_RELEASE_TYPE_ALPHA)
BETA (b) = 1 (ABT_RELEASE_TYPE_BETA)
RC (rc) = 2 (ABT_RELEASE_TYPE_RC)
PATCH (p) = 3 (ABT_RELEASE_TYPE_PATCH)

ABT_NUMVERSION has 1 digit for MAJ, 2 digits for MIN, 2 digits for REV, 1 digit for EXT, and 2 digits for EXT_NUMBER. For example, 1.0.7rc1 is converted to the numeric version 10007201.

Definition at line 68 of file abt.h.

◆ ABT_VERSION

#define ABT_VERSION   "1.1"

Version string of Argobots.

ABT_VERSION is the version string of Argobots. ABT_VERSION uses the following format:

ABT_VERSION = [MAJ].[MIN].[REV][EXT][EXT_NUMBER]
Example: ABT_VERSION = 1.0.7rc1 represents
MAJ = 1
MIN = 0
REV = 7
EXT = rc
EXT_NUMBER = 1

Regular releases are treated as patch 0.

Definition at line 46 of file abt.h.

Typedef Documentation

◆ ABT_info_query_kind

Query type for ABT_info_query_config().

Definition at line 1048 of file abt.h.

Enumeration Type Documentation

◆ ABT_info_query_kind

Query kind for ABT_info_query_config().

Enumerator
ABT_INFO_QUERY_KIND_ENABLED_DEBUG 

Whether the debug mode is enabled or not

ABT_INFO_QUERY_KIND_ENABLED_PRINT_ERRNO 

Whether Argobots prints an error number when an error happens or not

ABT_INFO_QUERY_KIND_ENABLED_LOG 

Whether Argobots prints a debug message or not

ABT_INFO_QUERY_KIND_ENABLED_VALGRIND 

Whether Argobots is configured to be Valgrind friendly or not

ABT_INFO_QUERY_KIND_ENABLED_CHECK_ERROR 

Whether an error is checked or not

ABT_INFO_QUERY_KIND_ENABLED_CHECK_POOL_PRODUCER 

Whether a pool access violation regarding producer is checked or not

ABT_INFO_QUERY_KIND_ENABLED_CHECK_POOL_CONSUMER 

Whether a pool access violation regarding consumer is checked or not

ABT_INFO_QUERY_KIND_ENABLED_PRESERVE_FPU 

Whether floating-point registers are saved on context switching or not

ABT_INFO_QUERY_KIND_ENABLED_THREAD_CANCEL 

Whether the thread cancellation feature is supported or not

ABT_INFO_QUERY_KIND_ENABLED_TASK_CANCEL 

Whether the task cancellation feature is supported or not

ABT_INFO_QUERY_KIND_ENABLED_MIGRATION 

Whether the thread and task migration feature is supported or not

ABT_INFO_QUERY_KIND_ENABLED_STACKABLE_SCHED 

Whether the stackable scheduler feature is supported or not

ABT_INFO_QUERY_KIND_ENABLED_EXTERNAL_THREAD 

Whether the external thread feature is supported or not

ABT_INFO_QUERY_KIND_ENABLED_SCHED_SLEEP 

Whether a predefined scheduler sleeps when idle or not

ABT_INFO_QUERY_KIND_ENABLED_PRINT_CONFIG 

Whether the Argobots configuration is printed in the top-level ABT_init() or not

ABT_INFO_QUERY_KIND_ENABLED_AFFINITY 

Whether the affinity setting is supported or not

ABT_INFO_QUERY_KIND_MAX_NUM_XSTREAMS 

The maximum number of execution streams

ABT_INFO_QUERY_KIND_DEFAULT_THREAD_STACKSIZE 

Default stack size of ULTs

ABT_INFO_QUERY_KIND_DEFAULT_SCHED_STACKSIZE 

Default stack size of ULT-type schedulers

ABT_INFO_QUERY_KIND_DEFAULT_SCHED_EVENT_FREQ 

Default event-checking frequency of a predefined scheduler

ABT_INFO_QUERY_KIND_DEFAULT_SCHED_SLEEP_NSEC 

Default sleep time of a predefined scheduler

ABT_INFO_QUERY_KIND_ENABLED_TOOL 

Whether the tool interface is enabled or not

ABT_INFO_QUERY_KIND_FCONTEXT 

Whether fcontext is used for context switch or not

ABT_INFO_QUERY_KIND_DYNAMIC_PROMOTION 

Whether dynamic promotion is used for context switch or not

ABT_INFO_QUERY_KIND_ENABLED_STACK_UNWIND 

Whether the stack unwinding feature is enabled or not

ABT_INFO_QUERY_KIND_ENABLED_STACK_OVERFLOW_CHECK 

Whether the stack overflow check is enabled or not

ABT_INFO_QUERY_KIND_WAIT_POLICY 

Wait policy

ABT_INFO_QUERY_KIND_ENABLED_LAZY_STACK_ALLOC 

Whether a ULT stack is lazily allocated by default or not

Definition at line 601 of file abt.h.

Function Documentation

◆ ABT_info_print_all_xstreams()

int ABT_info_print_all_xstreams ( FILE *  fp)

Print the information of all execution streams.

ABT_info_print_all_xstreams() writes the information of all execution streams to the output stream fp.

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED when Argobots is not initialized.
[Argobots 2.0] This routine prints the information and returns ABT_SUCCESS when Argobots is not initialized.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
[Argobots 1.x] This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
[Argobots 2.0] This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
Returns
Error code

Definition at line 522 of file info.c.

◆ ABT_info_print_config()

int ABT_info_print_config ( FILE *  fp)

Print the runtime information of Argobots.

ABT_info_print_config() writes the runtime information of Argobots to the output stream fp.

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED when Argobots is not initialized.
[Argobots 2.0] This routine prints the information and returns ABT_SUCCESS when Argobots is not initialized.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
[Argobots 1.x] This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
[Argobots 2.0] This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
Returns
Error code

Definition at line 473 of file info.c.

◆ ABT_info_print_pool()

int ABT_info_print_pool ( FILE *  fp,
ABT_pool  pool 
)

Print the information of a pool.

ABT_info_print_pool() writes the information of the pool pool to the output stream fp.

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_INV_POOL when pool is ABT_POOL_NULL.
[Argobots 2.0] This routine prints that pool is an invalid handle when pool is ABT_POOL_NULL.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
[in]poolpool handle
Returns
Error code

Definition at line 671 of file info.c.

◆ ABT_info_print_sched()

int ABT_info_print_sched ( FILE *  fp,
ABT_sched  sched 
)

Print the information of a scheduler.

ABT_info_print_sched() writes the information of the scheduler sched to the output stream fp.

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_INV_SCHED when sched is ABT_SCHED_NULL.
[Argobots 2.0] This routine prints that sched is an invalid handle when sched is ABT_SCHED_NULL.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
[in]schedscheduler handle
Returns
Error code

Definition at line 628 of file info.c.

◆ ABT_info_print_task()

int ABT_info_print_task ( FILE *  fp,
ABT_task  task 
)

Print the information of a work unit.

ABT_info_print_task() writes the information of the work unit task to the output stream fp. This routine is deprecated because its functionality is the same as that of ABT_info_print_thread().

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] The user cannot pass a ULT handle as task.
[Argobots 1.1] This routine accepts a ULT handle as task.
Rationale
Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_INV_TASK when task is ABT_THREAD_NULL or ABT_TASK_NULL.
[Argobots 2.0] This routine prints that task is an invalid handle when task is ABT_THREAD_NULL or ABT_TASK_NULL.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_INV_TASK is returned if task is ABT_THREAD_NULL or ABT_TASK_NULL.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
[in]taskwork unit handle
Returns
Error code

Definition at line 811 of file info.c.

◆ ABT_info_print_thread()

int ABT_info_print_thread ( FILE *  fp,
ABT_thread  thread 
)

Print the information of a work unit.

ABT_info_print_thread() writes the information of the work unit thread to the output stream fp.

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.
Rationale
Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_INV_THREAD when thread is ABT_THREAD_NULL or ABT_TASK_NULL.
[Argobots 2.0] This routine prints that thread is an invalid handle when thread is ABT_THREAD_NULL or ABT_TASK_NULL.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_INV_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
[in]threadwork unit handle
Returns
Error code

Definition at line 719 of file info.c.

◆ ABT_info_print_thread_attr()

int ABT_info_print_thread_attr ( FILE *  fp,
ABT_thread_attr  attr 
)

Print the information of a ULT attribute.

ABT_info_print_thread_attr() writes the information of the ULT attribute attr to the output stream fp.

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_INV_THREAD_ATTR when attr is ABT_THREAD_ATTR_NULL.
[Argobots 2.0] This routine prints that attr is an invalid handle when attr is ABT_THREAD_ATTR_NULL.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_INV_THREAD_ATTR is returned if attr is ABT_THREAD_ATTR_NULL.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
[in]attrULT attribute handle
Returns
Error code

Definition at line 762 of file info.c.

◆ ABT_info_print_thread_stack()

int ABT_info_print_thread_stack ( FILE *  fp,
ABT_thread  thread 
)

Print stack of a work unit.

ABT_info_print_thread_stack() prints the information of the stack of the work unit thread to the output stream fp.

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.
Rationale
Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_INV_THREAD when thread is ABT_THREAD_NULL or ABT_TASK_NULL.
[Argobots 2.0] This routine prints that thread is an invalid handle when thread is ABT_THREAD_NULL or ABT_TASK_NULL.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
This routine can be called in any execution context. Argobots does not need to be initialized. This routine may switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_INV_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
If thread is running, the results are undefined.
Parameters
[in]fpoutput stream
[in]threadwork unit handle
Returns
Error code

Definition at line 860 of file info.c.

◆ ABT_info_print_thread_stacks_in_pool()

int ABT_info_print_thread_stacks_in_pool ( FILE *  fp,
ABT_pool  pool 
)

Print stacks of all work units in a pool.

ABT_info_print_thread_stacks_in_pool() prints the information of stacks of all work units in the pool pool to the output stream fp. pool must support p_print_all().

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_INV_POOL when pool is ABT_POOL_NULL.
[Argobots 2.0] This routine prints that pool is an invalid handle when pool is ABT_POOL_NULL.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
This routine can be called in any execution context. Argobots does not need to be initialized. This routine may switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_POOL is returned if pool does not support p_print_all().
[Argobots 1.x] ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
[in]poolpool handle
Returns
Error code

Definition at line 925 of file info.c.

◆ ABT_info_print_xstream()

int ABT_info_print_xstream ( FILE *  fp,
ABT_xstream  xstream 
)

Print the information of an execution stream.

ABT_info_print_xstream() writes the information of the execution stream xstream to the output stream fp.

Note
The information written by this routine is meant for debugging and diagnosis, so the contents and the format of the printed information can be changed because of an update of the internal implementation of Argobots. A program that relies on the output of this routine is non-conforming.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_INV_XSTREAM when xstream is ABT_XSTREAM_NULL.
[Argobots 2.0] This routine prints that xstream is an invalid handle when xstream is ABT_XSTREAM_NULL.
Rationale
The information routines are primarily for debugging and diagnosis, so they should avoid returning an error.
Execution context
This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
Undefined behavior
If fp is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
Parameters
[in]fpoutput stream
[in]xstreamexecution stream handle
Returns
Error code

Definition at line 585 of file info.c.

◆ ABT_info_query_config()

int ABT_info_query_config ( ABT_info_query_kind  query_kind,
void *  val 
)

Retrieve the configuration information.

ABT_info_query_config() returns the configuration information associated with the query kind query_kind through val.

The retrieved information is selected via query_kind.

  • ABT_INFO_QUERY_KIND_ENABLED_DEBUG

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the debug mode. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_PRINT_ERRNO

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to print an error number when an error occurs. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_LOG

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to print debug messages. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_VALGRIND

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to be Valgrind friendly. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_CHECK_ERROR

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_FALSE if Argobots is configured to ignore some error checks. Otherwise, val is set to ABT_TRUE

  • ABT_INFO_QUERY_KIND_ENABLED_CHECK_POOL_PRODUCER

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_FALSE if Argobots is configured to ignore an access violation error regarding pool producers. Otherwise, val is set to ABT_TRUE.

  • ABT_INFO_QUERY_KIND_ENABLED_CHECK_POOL_CONSUMER

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_FALSE if Argobots is configured to ignore an access violation error regarding pool consumers. Otherwise, val is set to ABT_TRUE.

  • ABT_INFO_QUERY_KIND_ENABLED_PRESERVE_FPU

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to save floating-point registers on user-level context switching. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_THREAD_CANCEL

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the thread cancellation feature. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_TASK_CANCEL

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the task cancellation feature. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_MIGRATION

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the thread/task migration feature. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_STACKABLE_SCHED

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the stackable scheduler feature. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_EXTERNAL_THREAD

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the external thread feature. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_SCHED_SLEEP

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the sleep feature for predefined schedulers. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_PRINT_CONFIG

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to print all the configuration settings in the top-level ABT_init(). Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_AFFINITY

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the affinity setting. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_MAX_NUM_XSTREAMS

    val must be a pointer to a variable of type unsigned int. val is set to the maximum number of execution streams in Argobots.

  • ABT_INFO_QUERY_KIND_DEFAULT_THREAD_STACKSIZE

    val must be a pointer to a variable of type size_t. val is set to the default stack size of ULTs.

  • ABT_INFO_QUERY_KIND_DEFAULT_SCHED_STACKSIZE

    val must be a pointer to a variable of type size_t. val is set to the default stack size of ULT-type schedulers.

  • ABT_INFO_QUERY_KIND_DEFAULT_SCHED_EVENT_FREQ

    val must be a pointer to a variable of type uint64_t. val is set to the default event-checking frequency of predefined schedulers.

  • ABT_INFO_QUERY_KIND_DEFAULT_SCHED_SLEEP_NSEC

    val must be a pointer to a variable of type uint64_t. val is set to the default sleep time of predefined schedulers in nanoseconds.

  • ABT_INFO_QUERY_KIND_ENABLED_TOOL

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the tool feature. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_FCONTEXT

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to use fcontext. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_DYNAMIC_PROMOTION

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the dynamic promotion optimization. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_STACK_UNWIND

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable the stack unwinding feature. Otherwise, val is set to ABT_FALSE.

  • ABT_INFO_QUERY_KIND_ENABLED_STACK_OVERFLOW_CHECK

    val must be a pointer to a variable of type int. val is set to 1 if Argobots is configured to use a stack canary to check stack overflow. val is set to 2 if Argobots is configured to use an mprotect-based stack guard but ignore an error of mprotect(). val is set to 3 if Argobots is configured to use an mprotect-based stack guard and assert an error of mprotect(). Otherwise, val is set to 0.

  • ABT_INFO_QUERY_KIND_WAIT_POLICY

    val must be a pointer to a variable of type int. val is set to 0 if the wait policy of Argobots is passive. val is set to 1 if the wait policy of Argobots is active.

  • ABT_INFO_QUERY_KIND_ENABLED_LAZY_STACK_ALLOC

    val must be a pointer to a variable of type ABT_bool. val is set to ABT_TRUE if Argobots is configured to enable lazy allocation for ULT stacks by default. Otherwise, val is set to ABT_FALSE.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED if Argobots is not initialized.
[Argobots 2.0] This routine sets val and returns ABT_SUCCESS even when Argobots is not initialized if the queried information can be retrieved without Argobots initialization.
Rationale
Retrieving static configurations before initializing Argobots is helpful to check if the Argobots library is configured to enable necessary features.
Execution context
[Argobots 1.x] This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
[Argobots 2.0] This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_QUERY_KIND is returned if query_kind is not a valid info query kind.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.
[Argobots 2.0] ABT_ERR_UNINITIALIZED is returned if the queried information requires initialized Argobots while Argobots is not initialized.
Undefined behavior
If val is NULL, the results are undefined.
Parameters
[in]query_kindquery kind
[out]valresult
Returns
Error code

Definition at line 216 of file info.c.

◆ ABT_info_trigger_print_all_thread_stacks()

int ABT_info_trigger_print_all_thread_stacks ( FILE *  fp,
double  timeout,
void(*)(ABT_bool, void *)  cb_func,
void *  arg 
)

Print stacks of work units in pools associated with all the main schedulers.

ABT_info_trigger_print_all_thread_stacks() tries to print the information of stacks of all work units stored in pools associated with all the main schedulers to the output stream fp. This routine itself does not print the information; this routine immediately returns after updating a flag. The stack information is printed when all execution streams stop at ABT_xstream_check_events().

If timeout is negative, the stack information is printed only after all the execution streams stop at ABT_xstream_check_events(). If timeout is nonnegative, one of the execution streams that stop at ABT_xstream_check_events() starts to print the stack information even if some of the execution streams do not stop at ABT_xstream_check_events() within a certain time period specified by timeout in seconds. In this case, this routine might not work correctly and at worst crashes a program. The stack information is never printed if no execution stream executes ABT_xstream_check_events().

The callback function cb_func() is called after completing printing stacks unless it is registered. The first argument of cb_func() is set to ABT_TRUE if timeout is nonnegative and not all the execution streams stop within timeout. Otherwise, the first argument is set to ABT_FALSE. The second argument of cb_func() is the user-defined data arg passed to this routine. The caller of cb_func() is undefined, so a program that relies on the caller of cb_func() is non-conforming. Neither signal-safety nor thread-safety is required for cb_func().

The following work units are not captured by this routine:

  • Work units that are suspending (e.g., by ABT_thread_suspend()).
  • Work units in pools that are not associated with main schedulers.

Calling ABT_info_trigger_print_all_thread_stacks() multiple times updates old values. The values are atomically updated.

Note
This routine prints the information in a best-effort basis. Specifically, this routine does not return an error regarding fp to either the caller of this routine or cb_func().
If the timeout mechanism is used, the program may crash, so this functionality should be used only for debugging and diagnosis.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT. This routine is signal-safe. Note that it is the user's responsibility to call this function properly by, for example, loading the Argobots library and/or resolving the symbol of this routine in a signal handler.
Errors
ABT_SUCCESS is returned if this routine succeeds.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If fp is NULL, the results are undefined.
If cb_func is NULL, the results are undefined.
If an error occurs regarding fp, the results are undefined.
If the internal state of the Argobots is changed in cb_func(), the results are undefined.
Parameters
[in]fpoutput stream
[in]timeouttimeout in seconds
[in]cb_funccallback function
[in]argargument passed to cb_func()
Returns
Error code

Definition at line 1009 of file info.c.