diff --git a/Doxyfile.in b/Doxyfile.in index f79168e11..5406b22a8 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -1818,7 +1818,7 @@ ALIASES += undefined="\par Undefined behavior" ALIASES += DOC_CONTEXT_ANY="This routine can be called in any execution context. Argobots does not need to be initialized." -ALIASES += DOC_CONTEXT_ANY_NOTASK="This routine can be called in a ULT context and an external thread context. Argobots does not need to be initialized." +ALIASES += DOC_CONTEXT_ANY_NOTASK="This routine can be called in a ULT context or an external thread context. Argobots does not need to be initialized." ALIASES += DOC_CONTEXT_CTXSWITCH="This routine may switch the context of the calling ULT." @@ -1828,9 +1828,9 @@ ALIASES += DOC_CONTEXT_FINALIZE="This routine must be called by the same caller ALIASES += DOC_CONTEXT_INIT="This routine can be called in any execution context. Argobots must be initialized." -ALIASES += DOC_CONTEXT_INIT_NOEXT="This routine can be called in a ULT context and a tasklet context. Argobots must be initialized." +ALIASES += DOC_CONTEXT_INIT_NOEXT="This routine can be called in a ULT context or a tasklet context. Argobots must be initialized." -ALIASES += DOC_CONTEXT_INIT_NOTASK="This routine can be called in a ULT context and an external thread context. Argobots must be initialized." +ALIASES += DOC_CONTEXT_INIT_NOTASK="This routine can be called in a ULT context or an external thread context. Argobots must be initialized." ALIASES += DOC_CONTEXT_INIT_SCHED{1}="This routine can be called by a work unit that is associated with \1. Argobots must be initialized." @@ -1842,7 +1842,7 @@ ALIASES += DOC_CONTEXT_NOCTXSWITCH="This routine does not switch the context of ALIASES += DOC_CONTEXT_NOTE_SIGNAL_SAFE="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." -ALIASES += DOC_CONTEXT_TOOL_CALLBACK{1}="This routine can be called only in a tool callback function \1." +ALIASES += DOC_CONTEXT_TOOL_CALLBACK="This routine can be called only in a tool callback function." #--------------------------------------------------------------------------- # Description @@ -1870,69 +1870,67 @@ ALIASES += DOC_DESC_ATOMICITY_XSTREAM_REQUEST="Requests for execution streams ar ALIASES += DOC_DESC_ATOMICITY_XSTREAM_STATE="Management of states of execution streams is performed atomically." -ALIASES += DOC_DESC_REPLACEMENT{1}="This routine will be replaced by \1 in the future." - ALIASES += DOC_DESC_SCHED_AUTOMATIC{1}="If \1 is not configured to be automatically freed, it is the user's responsibility to free \1 after its use unless \c newsched is associated with the main scheduler of the primary execution stream. If \1 is configured to be automatically freed, \1 is automatically freed when a work unit associated with \1 is freed. If the user never associates \1 with a work unit (e.g., by \c ABT_pool_add_sched() or \c ABT_xstream_set_main_sched()), it is the user's responsibility to free \1." -ALIASES += DOC_DESC_TIMER_RESOLUTION="The resolution of elapsed time depends on the clock resolution by the system." +ALIASES += DOC_DESC_TIMER_RESOLUTION="The resolution of elapsed time depends on the clock resolution of the system." -ALIASES += DOC_DESC_V10_ACCEPT_TASK{1}="\DOC_V10 The user cannot pass a tasklet handle as \1.\n \DOC_V11 This routine accepts a tasklet handle as \1. @rationale Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 has introduced this change since this change does not break the compatibility of API and ABI of Argobots 1.0. @endrationale" +ALIASES += DOC_DESC_V10_ACCEPT_TASK{1}="\DOC_V10 The user cannot pass a tasklet handle as \1.\n \DOC_V11 This routine accepts a tasklet handle as \1. @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. @endrationale" -ALIASES += DOC_DESC_V10_ACCEPT_THREAD{1}="\DOC_V10 The user cannot pass a ULT handle as \1.\n \DOC_V11 This routine accepts a ULT handle as \1. @rationale Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 has introduced this change since this change does not break the compatibility of API and ABI of Argobots 1.0. @endrationale" +ALIASES += DOC_DESC_V10_ACCEPT_THREAD{1}="\DOC_V10 The user cannot pass a ULT handle as \1.\n \DOC_V11 This routine accepts a ULT handle as \1. @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. @endrationale" -ALIASES += DOC_DESC_V10_ACCESS_VIOLATION="\DOC_V10 If a pool access violation happens regarding an access type of a pool, an error is returned.\n \DOC_V11 If a pool access violation happens regarding an access type of a pool, the results are undefined. @rationale The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without any problem if it is no simultaneously accessed, although it is a user error. Such an error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Correctly implementing the access violation check could break the actual API compatibility. From Argobots 1.1, it is the user's responsibility to manage access to pools. @endrationale" +ALIASES += DOC_DESC_V10_ACCESS_VIOLATION="\DOC_V10 If a pool access violation happens regarding an access type of a pool, an error is returned.\n \DOC_V11 If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined. @rationale The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools. @endrationale" ALIASES += DOC_DESC_V10_ALWAYS_SCHED_TYPE_ULT="\DOC_V10 If \c ABT_SCHED_TYPE_TASK is set, the created scheduler runs on a tasklet.\n \DOC_V11 All schedulers run on ULTs. @rationale A scheduler that cannot yield is almost useless; such a scheduler is highly restrictive while it provides tiny performance benefits. Argobots 1.1 always creates a ULT-based scheduler regardless of \c ABT_sched_type. @endrationale" ALIASES += DOC_DESC_V10_BARRIER_NUM_WAITERS{1}="\DOC_V10 This routine accepts zero as \c num_waiters.\n \DOC_V11 This routine returns \c ABT_ERR_INV_ARG if \c num_waiters is zero. @rationale A barrier whose \c num_waiters is 0 cannot define a wait operation and should be prohibited. Note that even Argobots 1.0 does not allow \c ABT_barrier_wait() with a barrier whose \c num_waiters is 0. @endrationale" -ALIASES += DOC_DESC_V10_ERROR_CODE_CHANGE{3}="\DOC_V10 \1 is returned if \3.\n \DOC_V11 \2 is returned if \3. @rationale Argobots 1.0 returned an error code which is obviously wrong. Argobots 1.1 fixes the error code for consistent behavior with other Argobots routines. @endrationale" +ALIASES += DOC_DESC_V10_ERROR_CODE_CHANGE{3}="\DOC_V10 \1 is returned if \3.\n \DOC_V11 \2 is returned if \3. @rationale Argobots 1.0 returned a wrong error code. Argobots 1.1 fixes the error code for consistent behavior with other Argobots routines. @endrationale" ALIASES += DOC_DESC_V10_EVENTUAL_UPDATE_READY_BUFFER{1}="\DOC_V10 This routine updates the memory buffer of \1 and returns \c ABT_SUCCESS if \1 is ready.\n \DOC_V11 This routine returns \c ABT_ERR_EVENTUAL if \1 is ready. @rationale An update of the memory buffer when \1 is ready breaks the semantics of \c eventual. Such an update should be prohibited. @endrationale" -ALIASES += DOC_DESC_V10_FUTURE_COMPARTMENT_ORDER="\DOC_V10 The order of elements of \c arg passed to \c cb_func() is the same order as the \c ABT_future_set() calls are terminated.\n \DOC_V11 The order of elements of \c arg passed to \c cb_func() is undefined. @rationale This specification in Argobots 1.0 is unclear and unreasonable because the exact timing of termination of \c ABT_future_set() is not observable if \c ABT_future_set() is called concurrently. @endrationale" +ALIASES += DOC_DESC_V10_FUTURE_COMPARTMENT_ORDER="\DOC_V10 The order of elements of \c arg passed to \c cb_func() is the same order as the \c ABT_future_set() calls are terminated.\n \DOC_V11 The order of elements of \c arg passed to \c cb_func() is undefined. @rationale This specification in Argobots 1.0 is not reasonable because the exact timing of termination of \c ABT_future_set() is not observable if \c ABT_future_set() is called concurrently. @endrationale" ALIASES += DOC_DESC_V10_NOEXT{1}="\DOC_V10 If an external thread calls this routine, \1 is returned.\n \DOC_V11 An external thread may call this routine. @rationale Argobots 1.0 narrows the type of the caller without any reason. Argobots 1.1 fixes it. @endrationale" -ALIASES += DOC_DESC_V10_POOL_NOACCESS="\DOC_V10 The Argobots runtime respects an access type of a pool and returns an error if possible if a pool access violation happens regarding an access type of a pool.\n \DOC_V11 The Argobots runtime does not check an access type of a pool. If a pool access violation happens regarding an access type of a pool, the results are undefined. @rationale This access type was used for access violation error check. This check will be removed in Argobots 1.1 since correctly implementing the access violation check could break the actual API compatibility. From Argobots 1.1, it is the user's responsibility to manage access to pools. @endrationale" +ALIASES += DOC_DESC_V10_POOL_NOACCESS="\DOC_V10 The Argobots runtime respects an access type of a pool and returns an error in a best-effort basis if a pool access violation happens regarding an access type of a pool.\n \DOC_V11 The Argobots runtime does not check an access type of a pool. If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined. @rationale The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools. @endrationale" ALIASES += DOC_DESC_V10_POOL_NOTASK="\DOC_V10 A type of \c ABT_unit is \c ABT_UNIT_TYPE_TASK if an encapsulated work unit is a tasklet. Such a unit is created by \c u_create_from_task(). \n \DOC_V11 A type of any \c ABT_unit is \c ABT_UNIT_TYPE_THERAD. Accordingly, \c u_create_from_thread() is called to create \c ABT_unit for both ULTs and tasklets. @rationale In Argobots 1.0, the user needs to use a map (e.g., a hash table) to check if a type of a given \c ABT_unit is either \c ABT_UNIT_TYPE_THREAD or \c ABT_UNIT_TYPE_TASK, which makes the implementation of a user-defined pool extremely tedious. Argobots 1.1 marks these functions as unused to ease the implementation. @endrationale" ALIASES += DOC_DESC_V10_INCOMPLETE_SCHED_SIZE_CHECK{2}="\DOC_V10 If pools associated with the current main scheduler of \1 are not empty, \2 is returned.\n \DOC_V11 This routine works even if pools associated with the current main scheduler of \1 are not empty. @rationale This check unnecessarily limits the applicability of this routine. It is the user's responsibility to handle work units in pools associated with the old main scheduler, e.g., by migrating them to other pools. @endrationale" -ALIASES += DOC_DESC_V10_CRUDE_TERMINATION_CHECK{2}="\DOC_V10 \2 is returned if the runtime finds that \1 is terminated.\n \DOC_V11 The results are undefined if \1 is terminated. @rationale Proper implementation of this check is expensive since it requires atomic management of a work unit state and a request. Argobots 1.1 eliminates this check. @endrationale" +ALIASES += DOC_DESC_V10_CRUDE_TERMINATION_CHECK{2}="\DOC_V10 \2 is returned if the runtime finds that \1 is terminated.\n \DOC_V11 The results of this routine are undefined if \1 is terminated. @rationale Proper implementation of this check is expensive since it requires atomic management of a work unit state and a request. Argobots 1.1 eliminates this check. @endrationale" -ALIASES += DOC_DESC_V10_REJECT_MUTEX_ATTR_NULL{1}="\DOC_V10 This routine returns \c ABT_ERR_INV_MUTEX_ATTR if \1 is \c ABT_MUTEX_ATTR_NULL.\n \DOC_V11 This routine uses the default mutex attributes if \1 is \c ABT_MUTEX_ATTR_NULL. @rationale Most of the Argobots routines use the default attributes if the given configuration or attributes are NULL. This routine should also follow this basic rule. @endrationale" +ALIASES += DOC_DESC_V10_REJECT_MUTEX_ATTR_NULL{1}="\DOC_V10 This routine returns \c ABT_ERR_INV_MUTEX_ATTR if \1 is \c ABT_MUTEX_ATTR_NULL.\n \DOC_V11 This routine uses the default mutex attributes if \1 is \c ABT_MUTEX_ATTR_NULL. @rationale Most of the Argobots routines use the default attributes when a NULL handle is passed as a configuration or an attribute. This routine should follow this behavior. @endrationale" ALIASES += DOC_DESC_V1X_ERROR_CODE_CHANGE{3}="\DOC_V1X \1 is returned if \3.\n \DOC_V20 \2 is returned if \3. @rationale Argobots 2.0 changes the error code for consistent behavior with other Argobots routines. @endrationale" -ALIASES += DOC_DESC_V1X_NOEXT{1}="\DOC_V1X If an external thread calls this routine, \1 is returned.\n \DOC_V20 An external thread may call this routine. @rationale Argobots 2.0 allows an external thread as much as possible unless it is semantically wrong. @endrationale" +ALIASES += DOC_DESC_V1X_NOEXT{1}="\DOC_V1X If an external thread calls this routine, \1 is returned.\n \DOC_V20 An external thread may call this routine. @rationale Argobots 2.0 allows an external thread where possible unless it is semantically inappropriate. @endrationale" ALIASES += DOC_DESC_V1X_NOTASK{1}="\DOC_V1X If a tasklet calls this routine, \1 is returned.\n \DOC_V20 A tasklet may call this routine. @rationale Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. @endrationale" ALIASES += DOC_DESC_V1X_NOYIELDABLE{1}="\DOC_V1X If a ULT calls this routine, \1 is returned.\n \DOC_V20 A ULT may call this routine. @rationale Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. @endrationale" -ALIASES += DOC_DESC_V1X_NULL_PTR{2}="\DOC_V1X If \1 is \c NULL, \2 is returned.\n \DOC_V20 If \1 is \c NULL, the results are undefined. @rationale Argobots 2.0 will not check NULL pointers. @endrationale" +ALIASES += DOC_DESC_V1X_NULL_PTR{2}="\DOC_V1X If \1 is \c NULL, \2 is returned.\n \DOC_V20 If \1 is \c NULL, the results of this routine are undefined. @rationale Argobots 2.0 will not check NULL pointers. @endrationale" -ALIASES += DOC_DESC_V1X_P_POP_WAIT="\DOC_V1X \c ABT_pool_def does not define \c p_pop_wait. \n \DOC_V20 \c ABT_pool_def defines \c p_pop_wait. @rationale To maintain the ABI compatibility, \c p_pop_wait is excluded from \c ABT_pool_def. @endrationale" +ALIASES += DOC_DESC_V1X_P_POP_WAIT="\DOC_V1X \c ABT_pool_def does not define \c p_pop_wait. \n \DOC_V20 \c ABT_pool_def defines \c p_pop_wait. @rationale To maintain the ABI compatibility, Argobots 1.x does not define \c p_pop_wait in \c ABT_pool_def. @endrationale" -ALIASES += DOC_DESC_V1X_CRUDE_BLOCKED_CHECK{2}="\DOC_V1X \2 is returned if \1 is not suspended.\n \DOC_V20 The results are undefined if \1 is not suspended. @rationale This check of the current implementation is not atomic while making this check atomic is expensive. From Argobots 2.0, it becomes the user's responsibility to guarantee that \1 has been suspended. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call \c ABT_thread_resume() for the same ULT. @endrationale" +ALIASES += DOC_DESC_V1X_CRUDE_BLOCKED_CHECK{2}="\DOC_V1X \2 is returned if \1 is not suspended.\n \DOC_V20 The results of this routine are undefined if \1 is not suspended. @rationale This check of the current implementation is not atomic while making this check atomic is expensive. From Argobots 2.0, it becomes the user's responsibility to guarantee that \1 has been suspended. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call \c ABT_thread_resume() for the same ULT. @endrationale" -ALIASES += DOC_DESC_V1X_CRUDE_SCHED_USED_CHECK{2}="\DOC_V1X \2 is returned if this routine finds \1 is already used.\n \DOC_V20 The results are undefined if \1 is already used. @rationale The current implementation of this check is crude since whether a scheduler is used or not is not maintained atomically. From Argobots 2.0, it becomes the user's responsibility to guarantee that \1 is not used. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call any routines that attempt to use the same scheduler by assuming that only one of them would succeed. @endrationale" +ALIASES += DOC_DESC_V1X_CRUDE_SCHED_USED_CHECK{2}="\DOC_V1X \2 is returned if this routine finds \1 is already used.\n \DOC_V20 The results of this routine are undefined if \1 is already used. @rationale The current implementation of this check is crude since whether a scheduler is used or not is not maintained atomically. From Argobots 2.0, it becomes the user's responsibility to guarantee that \1 is not used. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call any routines that attempt to use the same scheduler by assuming that only one of them would succeed. @endrationale" -ALIASES += DOC_DESC_V1X_CRUDE_WAITER_CHECK{2}="\DOC_V1X \2 is returned if this routine finds a waiter on \1.\n \DOC_V20 The results are undefined if a waiter is blocked on \1. @rationale The current implementation of this check is crude considering the asynchronous nature of \1. From Argobots 2.0, it becomes the user's responsibility to ensure that no waiter is blocked on \1. @endrationale" +ALIASES += DOC_DESC_V1X_CRUDE_WAITER_CHECK{2}="\DOC_V1X \2 is returned if this routine finds a waiter on \1.\n \DOC_V20 The results of this routine are undefined if a waiter is blocked on \1. @rationale The current implementation of this check is crude considering the asynchronous nature of \1. From Argobots 2.0, it becomes the user's responsibility to ensure that no waiter is blocked on \1. @endrationale" -ALIASES += DOC_DESC_V1X_PRINT_HANDLE_INFO{3}="\DOC_V1X This routine returns \3 when \1 is \2.\n \DOC_V20 This routine prints that \1 is an invalid handle when \1 is \2. @rationale The information routines primarily for debugging and diagnosis should avoid returning an error as much as possible. @endrationale" +ALIASES += DOC_DESC_V1X_PRINT_HANDLE_INFO{3}="\DOC_V1X This routine returns \3 when \1 is \2.\n \DOC_V20 This routine prints that \1 is an invalid handle when \1 is \2. @rationale The information routines are primarily for debugging and diagnosis, so they should avoid returning an error. @endrationale" -ALIASES += DOC_DESC_V1X_PRINT_HANDLE_INFO{4}="\DOC_V1X This routine returns \4 when \1 is \2 or \3.\n \DOC_V20 This routine prints that \1 is an invalid handle when \1 is \2 or \3. @rationale The information routines primarily for debugging and diagnosis should avoid returning an error as much as possible. @endrationale" +ALIASES += DOC_DESC_V1X_PRINT_HANDLE_INFO{4}="\DOC_V1X This routine returns \4 when \1 is \2 or \3.\n \DOC_V20 This routine prints that \1 is an invalid handle when \1 is \2 or \3. @rationale The information routines are primarily for debugging and diagnosis, so they should avoid returning an error. @endrationale" -ALIASES += DOC_DESC_V1X_PRINT_RUNTIME_INFO="\DOC_V1X This routine returns \c ABT_ERR_UNINITIALIZED when Argobots is not initialized.\n \DOC_V20 This routine prints the queried information and returns \c ABT_SUCCESS when Argobots is not initialized. @rationale The information routines primarily for debugging and diagnosis should avoid returning an error as much as possible. @endrationale" +ALIASES += DOC_DESC_V1X_PRINT_RUNTIME_INFO="\DOC_V1X This routine returns \c ABT_ERR_UNINITIALIZED when Argobots is not initialized.\n \DOC_V20 This routine prints the information and returns \c ABT_SUCCESS when Argobots is not initialized. @rationale The information routines are primarily for debugging and diagnosis, so they should avoid returning an error. @endrationale" -ALIASES += DOC_DESC_V1X_RETURN_INFO_IF_POSSIBLE="\DOC_V1X This routine returns \c ABT_ERR_UNINITIALIZED if Argobots is not initialized.\n \DOC_V20 This routine returns \c ABT_ERR_UNINITIALIZED if Argobots is not initialized and the queried information cannot be retrieved when Argobots is not initialized. @rationale Retrieving static configurations before initializing Argobots is helpful to check if the loaded Argobots implements necessary features. @endrationale" +ALIASES += DOC_DESC_V1X_RETURN_INFO_IF_POSSIBLE="\DOC_V1X This routine returns \c ABT_ERR_UNINITIALIZED if Argobots is not initialized.\n \DOC_V20 This routine sets \c val and returns \c 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. @endrationale" -ALIASES += DOC_DESC_V1X_RETURN_UNINITIALIZED="\DOC_V1X This routine returns \c ABT_ERR_UNINITIALIZED if Argobots is not initialized.\n \DOC_V20 The results are undefined if Argobots is not initialized. @rationale From Argobots 2.0, all the Argobots routines that are not explicitly noted do not check if Argobots is initialized. This omission can reduce the branches that are mostly unnecessary. @endrationale" +ALIASES += DOC_DESC_V1X_RETURN_UNINITIALIZED="\DOC_V1X This routine returns \c ABT_ERR_UNINITIALIZED if Argobots is not initialized.\n \DOC_V20 The results of this routine are undefined if Argobots is not initialized. @rationale From Argobots 2.0, Argobots routines do not check if Argobots is initialized unless otherwise noted. This omission can reduce the branches that are unnecessary in most cases. @endrationale" -ALIASES += DOC_DESC_V1X_SCHED_GET_POOLS_IDX{4}="\DOC_V1X If the summation of \1 and \2 is larger than the number of pools associated with \3, this routine returns \c ABT_ERR_SCHED.\n \DOC_V20 This routine does not update elements of \4 if corresponding pool elements specified by \1 and \2 are out of range. @rationale The restriction is unnecessary and thus this behavior is deprecated. @endrationale" +ALIASES += DOC_DESC_V1X_SCHED_GET_POOLS_IDX{4}="\DOC_V1X If the summation of \1 and \2 is larger than the number of pools associated with \3, this routine returns \c ABT_ERR_SCHED.\n \DOC_V20 This routine does not update elements of \4 if corresponding pool elements specified by \1 and \2 are out of range. @rationale The original behavior is unnecessarily restrictive. Argobots 2.0 removes this check. @endrationale" ALIASES += DOC_DESC_V1X_SET_MIGRATABLE{2}="\DOC_V1X If \1 is the primary ULT or the work unit associated with the main scheduler, this routine has no effect and returns \c ABT_SUCCESS.\n \DOC_V20 If \1 is the primary ULT or the work unit associated with the main scheduler, this routine returns \2. @rationale The original behavior is error-prone since this routine does nothing but returns \c ABT_SUCCESS. @endrationale" @@ -2168,7 +2166,7 @@ ALIASES += DOC_NOTE_DEFAULT_THREAD_ATTRIBUTE="To see the details of the default ALIASES += DOC_NOTE_EFFECT_ABT_FINALIZE="\c ABT_finalize() frees the primary execution stream, its main scheduler, and pools associated with the main scheduler." -ALIASES += DOC_NOTE_INFO_PRINT="The information written by this routine is meant for debugging and diagnosis and 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." +ALIASES += DOC_NOTE_INFO_PRINT="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." ALIASES += DOC_NOTE_NO_PADDING{2}="This routine does not pad \1 until a total \2 elements have been written to \1. The remaining elements of \1 that are not written by this routine are unmodified." @@ -2176,7 +2174,9 @@ ALIASES += DOC_NOTE_POOL_SIZE="To see the details of the size of a pool, please ALIASES += DOC_NOTE_POOL_TOTAL_SIZE="To see the details of the total size of a pool, please check \c ABT_pool_get_total_size()." -ALIASES += DOC_NOTE_TIMING_REQUEST="The timing of the request fulfillment is undefined, so a program that relies on when the request is fulfilled is non-conforming." +ALIASES += DOC_NOTE_REPLACEMENT{1}="This routine will be replaced by \1 in the future." + +ALIASES += DOC_NOTE_TIMING_REQUEST="The timing of the request fulfillment is undefined, so a program that relies on the timing of the request fulfillment is non-conforming." #--------------------------------------------------------------------------- # Undefined behavior @@ -2230,7 +2230,7 @@ ALIASES += DOC_UNDEFINED_UNINIT="If Argobots is not initialized, the results are ALIASES += DOC_UNDEFINED_WAITER{1}="If there is a waiter blocked on \1, the results are undefined.\n" -ALIASES += DOC_UNDEFINED_WORK_UNIT_BLOCKED{1}="If \1 is blocked on by \2, the results are undefined.\n" +ALIASES += DOC_UNDEFINED_WORK_UNIT_BLOCKED{2}="If \1 is blocked on by a caller of \2, the results are undefined.\n" ALIASES += DOC_UNDEFINED_WORK_UNIT_IN_POOL{1}="If \1 is in a pool, the results are undefined.\n" @@ -2248,7 +2248,7 @@ ALIASES += DOC_UNDEFINED_WORK_UNIT_TERMINATED{1}="If \1 is terminated, the resul ALIASES += DOC_UNDEFINED_WORK_UNIT_UNSUSPENDED{1}="If \1 is not suspended, the results are undefined.\n" -ALIASES += DOC_UNDEFINED_XSTREAM_BLOCKED{2}="If \1 is blocked on by \2, the results are undefined.\n" +ALIASES += DOC_UNDEFINED_XSTREAM_BLOCKED{2}="If \1 is blocked on by a caller of \2, the results are undefined.\n" ALIASES += DOC_UNDEFINED_XSTREAM_NOT_RUNNING{1}="If \1 is not running, the results are undefined.\n" diff --git a/README.md b/README.md index a61ea32c0..623a9333a 100644 --- a/README.md +++ b/README.md @@ -1,135 +1,129 @@ - Argobots Release %VERSION% +# Argobots -Argobots is a lightweight, low-level threading and tasking framework. This -release is an experimental version of Argobots that contains features related to -user-level threads, tasklets, and some schedulers. +Argobots is a lightweight, low-level threading and tasking framework. -This README file should contain enough information to get you started with -Argobots. More information about Argobots can be found at -http://www.argobots.org. +README.md should contain enough information to get you started with Argobots. +1. [Getting Started](#1-getting-started) +2. [Testing Argobots](#2-testing-argobots) +3. [Reporting Problems](#3-reporting-problems) +4. [Alternate Configure Options](#4-alternate-configure-options) +5. [Compiler Flags](#5-compiler-flags) +6. [Developer Builds](#6-developer-builds) -1. Getting Started -2. Testing Argobots -3. Reporting Problems -4. Alternate Configure Options -5. Compiler Flags -6. Developer Builds - +- More information about Argobots can be found at https://www.argobots.org +- Complete Argobots API can be found at https://www.argobots.org/doxygen/latest/ ------------------------------------------------------------------------------- -1. Getting Started -================== +## 1. Getting Started The following instructions take you through a sequence of steps to get the -default configuration of Argobots up and running. - -(a) You will need the following prerequisites. - - - REQUIRED: This tar file argobots-%VERSION%.tar.gz - - - REQUIRED: A C compiler (gcc is sufficient) - - Also, you need to know what shell you are using since different shell has - different command syntax. Command "echo $SHELL" prints out the current shell - used by your terminal program. - -(b) Unpack the tar file and go to the top level directory: +default configuration of Argobots up and running. For compilation, Argobots +needs a C compiler (gcc is sufficient). - tar xzf argobots-%VERSION%.tar.gz - cd argobots-%VERSION% +Also, you need to know what shell you are using since different shell has +different command syntax. Command `echo $SHELL` prints out the current shell +used by your terminal program. - If your tar doesn't accept the z option, use +### (a) Preparation - gunzip argobots-%VERSION%.tar.gz - tar xf argobots-%VERSION%.tar - cd argobots-%VERSION% +(a.1) *If you downloaded a release tarball of Argobots*, unpack the tar file and +go to the top level directory: -(c) Choose an installation directory, say /home/USERNAME/argobots-install, -which is assumed to be non-existent or empty. +```sh + tar xzf argobots.tar.gz + cd argobots -(d) Configure Argobots specifying the installation directory: + ## If your `tar` doesn't accept the `z` option, use the following instead + # gunzip argobots.tar.gz + # tar xf argobots.tar + # cd argobots +``` - for csh and tcsh: +(a.2) *If you cloned Argobots from the GitHub page*, go to the top level +directory and create `configure`: - ./configure --prefix=/home/USERNAME/argobots-install |& tee c.txt +```sh + cd argobots + ./autogen.sh +``` - for bash and sh: +### (b) Choose an installation directory - ./configure --prefix=/home/USERNAME/argobots-install 2>&1 | tee c.txt +The installation directory should be non-existent or empty. +The following assumes `/home/USERNAME/argobots-install` - Bourne-like shells, sh and bash, accept "2>&1 |". Csh-like shell, csh and - tcsh, accept "|&". If a failure occurs, the configure command will display - the error. Most errors are straight-forward to follow. +### (c) Configure Argobots specifying the installation directory -(e) Build Argobots: +```sh + ./configure --prefix=/home/USERNAME/argobots-install 2>&1 | tee c.txt - for csh and tcsh: + ## If you are using csh or tcsh: + # ./configure --prefix=/home/USERNAME/argobots-install |& tee c.txt +``` - make |& tee m.txt +If a failure occurs, the configure command will display the error. Most errors +are straight-forward to follow. - for bash and sh: +### (d) Build Argobots: - make 2>&1 | tee m.txt +```sh + make 2>&1 | tee m.txt - This step should succeed if there were no problems with the preceding step. - Check file m.txt. If there were problems, do a "make clean" and then run - make again with V=1. + ## If you are using csh or tcsh: + # make |& tee m.txt +``` - make V=1 |& tee m.txt (for csh and tcsh) +This step should succeed if there were no problems with the preceding step. +Check file `m.txt`. If there were problems, do a `make clean` and then run +make again with `V=1`. - OR +```sh + make V=1 2>&1 | tee m.txt - make V=1 2>&1 | tee m.txt (for bash and sh) + ## If you are using csh or tcsh: + # make V=1 |& tee m.txt +``` - Then go to step 3 below, for reporting the issue to the Argobots developers - and other users. +If it does not work, go to step 3 below, for reporting the issue to the Argobots +developers and other users. -(f) Install Argobots: +### (e) Install Argobots: - for csh and tcsh: +```sh + make install 2>&1 | tee mi.txt - make install |& tee mi.txt + ## If you are using csh or tcsh: + # make install |& tee mi.txt +``` - for bash and sh: +This step collects all required files in the `bin` subdirectory of the directory +specified by the prefix argument to configure. - make install 2>&1 | tee mi.txt - This step collects all required executables and scripts in the bin - subdirectory of the directory specified by the prefix argument to configure. - -------------------------------------------------------------------------------- - -2. Testing Argobots -=================== +## 2. Testing Argobots To test Argobots, we package the Argobots test suite in the Argobots -distribution. You can run the test suite in the test directory using: +distribution. You can run the test suite in the `test` directory using: - make check - - OR - - make testing +```sh + make check +``` The distribution also includes some Argobots examples. You can run them in the -examples directory using: - - make check +`examples` directory using: - OR - - make testing +```sh + make check +``` If you run into any problems on running the test suite or examples, please follow step 3 below for reporting them to the Argobots developers and other users. -------------------------------------------------------------------------------- -3. Reporting Problems -===================== +## 3. Reporting Problems If you have problems with the installation or usage of Argobots, please follow these steps: @@ -151,12 +145,12 @@ Your email should contain the following files. ONCE AGAIN, PLEASE COMPRESS BEFORE SENDING, AS THE FILES CAN BE LARGE. Note that, depending on which step the build failed, some of the files might not exist. - argobots-%VERSION%/c.txt (generated in step 1(d) above) - argobots-%VERSION%/m.txt (generated in step 1(e) above) - argobots-%VERSION%/mi.txt (generated in step 1(f) above) - argobots-%VERSION%/config.log (generated in step 1(d) above) - - DID WE MENTION? DO NOT FORGET TO COMPRESS THESE FILES! +``` + argobots/c.txt (generated in step 1(c) above) + argobots/m.txt (generated in step 1(d) above) + argobots/mi.txt (generated in step 1(e) above) + argobots/config.log (generated in step 1(c) above) +``` Finally, please include the actual error you are seeing when running the application. If possible, please try to reproduce the error with a smaller @@ -167,22 +161,20 @@ github issues page (https://github.com/pmodels/argobots/issues). Even if you believe you have found a bug, we recommend you sending an email to discuss@argobots.org first. -------------------------------------------------------------------------------- -4. Alternate Configure Options -============================== +## 4. Alternate Configure Options Argobots has a number of other features. If you are exploring Argobots as part of a development project, you might want to tweak the Argobots build with the following configure options. A complete list of configuration options can be found using: +```sh ./configure --help +``` -------------------------------------------------------------------------------- -5. Compiler Flags -================= +## 5. Compiler Flags By default, Argobots automatically adds certain compiler optimizations to CFLAGS. The currently used optimization level is -O2. @@ -190,30 +182,28 @@ CFLAGS. The currently used optimization level is -O2. This optimization level can be changed with the --enable-fast option passed to configure. For example, to build Argobots with -O3, one can simply do: +```sh ./configure --enable-fast=O3 +``` -Or to disable all compiler optimizations, one can do: - - ./configure --disable-fast - -For more details of --enable-fast, see the output of "./configure --help". +For more details of `--enable-fast`, see the output of `./configure --help`. For performance testing, we recommend the following flags: - ./configure --enable-fast=O3,ndebug --enable-tls-model=initial-exec \ - --enable-affinity --disable-checks +```sh + ./configure --enable-perf-opt --enable-affinity --disable-checks +``` - OR +For debugging, we recommend the following flags: - ./configure --enable-perf-opt --enable-affinity --disable-checks +```sh + ./configure --enable-fast=O0 --enable-debug=most +``` -------------------------------------------------------------------------------- -6. Developer Builds -=================== +## 6. Developer Builds For Argobots developers who want to directly work on the primary version control system, there are a few additional steps involved (people using the release tarballs do not have to follow these steps). Details about these steps can be found here: https://github.com/pmodels/argobots/wiki/Getting-and-Building - diff --git a/maint/release.pl b/maint/release.pl index aec7054d0..ec4d8d999 100755 --- a/maint/release.pl +++ b/maint/release.pl @@ -17,6 +17,7 @@ my $root = cwd(); my $with_autoconf = ""; my $with_automake = ""; +my $enable_doxygen = 0; my $git_repo = ""; my $logfile = "release.log"; @@ -32,6 +33,7 @@ sub usage print "\t--append-commit-id append git commit description (optional)\n"; print "\t--with-autoconf autoconf directory (optional)\n"; print "\t--with-automake automake directory (optional)\n"; + print "\t--enable-doxygen enable doxygen (optional)\n"; print "\n"; @@ -120,6 +122,7 @@ sub run_cmd "append-commit-id!" => \$append_commit_id, "with-autoconf=s" => \$with_autoconf, "with-automake=s" => \$with_automake, + "enable-doxygen!" => \$enable_doxygen, "help" => \&usage ) or die "unable to parse options, stopped"; @@ -135,6 +138,14 @@ sub run_cmd check_package("latex"); check_package("autoconf"); check_package("automake"); +if ($enable_doxygen) { + check_package("doxygen"); + my $official_doxygen_ver = "1.8.17"; + my $doxygen_ver = `doxygen --version | head -n 1 | grep "$official_doxygen_ver"`; + if ($doxygen_ver eq "") { + die "ERROR: Doxygen ${official_doxygen_ver} is not installed. Consider setting --enable-doxygen. Stopped"; + } +} print("\n"); @@ -189,6 +200,9 @@ sub run_cmd system(qq(perl -p -i -e 's/\\[ABT_RELEASE_DATE_m4\\],\\[unreleased development copy\\]/[ABT_RELEASE_DATE_m4],[$date]/g' ./maint/version.m4)); print("done\n"); +# Add version information to README.md +system(qq(perl -p -i -e 's/^# Argobots\n/# Argobots ${version}\n/g' README.md)); + # Create configure print("===> Creating configure in the main codebase... "); chdir($expdir); @@ -210,17 +224,19 @@ sub run_cmd run_cmd("find . -name .tmp | xargs rm -rf"); print("done\n"); -# TODO: Get docs -#print("===> Creating secondary codebase for the docs... "); -#run_cmd("mkdir ${expdir}-build"); -#chdir("${expdir}-build"); -#run_cmd("${expdir}/configure"); -#run_cmd("(make doxygen)"); -#print("done\n"); -# -#print("===> Copying docs over... "); -#run_cmd("cp -a doc/doxygen/html ${expdir}/"); -#print("done\n"); +if ($enable_doxygen) { + # Create doxygen files + print("===> Creating secondary codebase for the docs... ${expdir}-build "); + run_cmd("mkdir ${expdir}-build"); + chdir("${expdir}-build"); + run_cmd("${expdir}/configure"); + run_cmd("(make doxygen)"); + print("done\n"); + + print("===> Copying docs over... cp -a doc/doxygen/html ${expdir}/ "); + run_cmd("cp -a doc/doxygen ${expdir}/doc"); + print("done\n"); +}; # Create the main tarball print("===> Creating the final argobots tarball... "); diff --git a/src/eventual.c b/src/eventual.c index a25b44952..397c246f0 100644 --- a/src/eventual.c +++ b/src/eventual.c @@ -15,11 +15,11 @@ * * \c ABT_eventual_create() creates a new eventual and returns its handle * through \c neweventual. \c neweventual is set to unready. If \c nbytes is - * greater than zero, \c neweventual has a memory buffer of \c nbytes bytes for - * \c neweventual. This memory buffer of \c neweventual can be set by - * \c ABT_eventual_set() and read by \c ABT_eventual_wait() and - * \c ABT_eventual_test(). If \c nbytes is zero, \c neweventual is used without - * passing the data from a setter to waiters. + * greater than zero, this routine allocates a memory buffer of \c nbytes bytes + * for \c neweventual. This memory buffer can be set by \c ABT_eventual_set() + * and read by \c ABT_eventual_wait() or \c ABT_eventual_test(). If \c nbytes + * is zero, the user cannot pass data from a setter to waiters through + * \c neweventual. * * \c neweventual must be freed by \c ABT_eventual_free() after its use. * @@ -335,8 +335,10 @@ int ABT_eventual_set(ABT_eventual eventual, void *value, int nbytes) * @ingroup EVENTUAL * @brief Reset a readiness of an eventual. * - * \c ABT_eventual_reset() makes the eventual \c eventual unready. This routine - * makes \c eventual unready irrespective of its readiness. + * \c ABT_eventual_reset() makes the eventual \c eventual unready. + * + * @note + * This routine makes \c eventual unready irrespective of its readiness. * * \DOC_DESC_ATOMICITY_EVENTUAL_READINESS * diff --git a/src/futures.c b/src/futures.c index 98937ef35..d20777516 100644 --- a/src/futures.c +++ b/src/futures.c @@ -24,14 +24,15 @@ * \c ABT_future_set() for a future that has no compartment.\n * \c cb_func() is never called if \c num_compartments is zero. * - * If \c cb_func is not \c NULL, a callback function \c cb_func() will be called - * just before all the compartments are set by \c ABT_future_set(). The caller - * of \c cb_func() is undefined, so a program that relies on the caller of - * \c cb_func() is non-conforming. Calling any routine for a future in - * \c cb_func() that is associated with the future causes undefined behavior. - * The argument \c arg of \c cb_func() is a properly aligned array each of - * which element stores \c value passed to \c ABT_future_set(). The contents of - * \c arg are read-only and may not be accessed after \c cb_func() finishes. + * If \c cb_func is not \c NULL, the callback function \c cb_func() is + * registered to \c future. \c cb_func() will be called before all the + * compartments are set by \c ABT_future_set(). The caller of \c cb_func() is + * undefined, so a program that relies on the caller of \c cb_func() is + * non-conforming. The state of the future that invokes \c cb_func() is + * undefined in \c cb_func(). The argument \c arg of \c cb_func() is a properly + * aligned array each of which element stores \c value passed to + * \c ABT_future_set(). The contents of \c arg are read-only and may not be + * accessed after \c cb_func() finishes. * * \c newfuture must be freed by \c ABT_future_free() after its use. * @@ -135,8 +136,8 @@ int ABT_future_free(ABT_future *future) * * The caller of \c ABT_future_wait() waits on the future \c future. If * \c future is ready, this routine returns immediately. If \c future is not - * ready, the caller of this routine suspends and will be resumed once \c future - * gets ready. + * ready, the caller of this routine suspends. The caller will be resumed once + * \c future gets ready. * * \DOC_DESC_ATOMICITY_FUTURE_READINESS * @@ -232,8 +233,9 @@ int ABT_future_test(ABT_future future, ABT_bool *is_ready) * * \c ABT_future_set() sets a value \c value to one of the unset compartments of * the future \c future. If all the compartments of \c future are set, this - * routine triggers a callback function of \c future if it is not \c NULL, makes - * \c future ready, and wakes up all waiters that are blocked on \c future. + * routine makes \c future ready and wakes up all waiters that are blocked on + * \c future. If the callback function is set to \c future, the callback + * function is triggered before \c future is set to ready. * * \DOC_DESC_ATOMICITY_FUTURE_READINESS * @@ -292,9 +294,11 @@ int ABT_future_set(ABT_future future, void *value) * @brief Reset readiness of a future. * * \c ABT_future_reset() resets the readiness of the future \c future. - * \c future gets ready if \c ABT_future_set() for \c future succeeds as many - * times as the number of compartments of the future. This routine makes - * \c future unready irrespective of its readiness. + * A future reset by this routine will get ready if \c ABT_future_set() succeeds + * as many times as the number of its compartments. + * + * @note + * This routine makes \c future unready irrespective of its readiness. * * \DOC_DESC_ATOMICITY_FUTURE_READINESS * diff --git a/src/global.c b/src/global.c index d32fd4449..8ce0215ff 100644 --- a/src/global.c +++ b/src/global.c @@ -32,9 +32,9 @@ static ABTD_atomic_uint32 g_ABTI_initialized = * \c ABT_init() initializes the Argobots execution environment. If Argobots * has not been initialized, the first caller of \c ABT_init() becomes the * primary ULT that is running on the primary execution stream. If Argobots has - * been already initialized, \c ABT_init() increments a reference counter - * atomically. This routine returns \c ABT_SUCCESS even if Argobots has been - * already initialized. + * already been initialized, \c ABT_init() increments a reference counter + * atomically. This routine returns \c ABT_SUCCESS even if Argobots has already + * been initialized. * * \DOC_DESC_ATOMICITY_ARGOBOTS_INIT * @@ -53,12 +53,12 @@ static ABTD_atomic_uint32 g_ABTI_initialized = * Argobots can be reinitialized after freeing Argobots. That is, \c ABT_init() * can be called again after Argobots is finalized by \c ABT_finalize(). * - * This routine ignores the arguments \c argc and \c argv. + * This routine does not use the arguments \c argc and \c argv. * * @note * Although the arguments are \c argc and \c argv, the caller of \c ABT_init() * does not need to be an external thread that starts a program (e.g., a POSIX - * thread that calls \c main()). + * thread that runs \c main()). * * @contexts * \DOC_CONTEXT_ANY \DOC_CONTEXT_CTXSWITCH @@ -67,8 +67,8 @@ static ABTD_atomic_uint32 g_ABTI_initialized = * \DOC_ERROR_SUCCESS * \DOC_ERROR_RESOURCE * - * @param[in] argc ignored parameter - * @param[in] argv ignored parameter + * @param[in] argc unused parameter + * @param[in] argv unused parameter * @return Error code */ int ABT_init(int argc, char **argv) @@ -104,19 +104,16 @@ int ABT_init(int argc, char **argv) * * \c ABT_finalize() is thread-safe, but calling \c ABT_finalize() concurrently * is discouraged because the user cannot guarantee the calling order of - * \c ABT_finialize() while \c ABT_finalize() needs to be called by the same + * \c ABT_finalize() although \c ABT_finalize() needs to be called by the same * caller as that of \c ABT_init() at the same nesting level. * - * If \c ABT_finalize() is called at the first nesting level, this routine - * deallocates and invalidates all the resources and the handles associated with - * Argobots unless otherwise noted. - * * @note * The current specification does not define which routine can be safely called - * during the finalization phase, for example, in the user-given scheduler - * finalization function \c free() that is associated with the main scheduler of - * the primary execution stream, which can be triggered by \c ABT_finalize(). - * The behavior of this routine will be clarified in the future. + * during the finalization phase. For example, the specification does not + * specify which routine can be safely used in the user-defined scheduler + * finalization function \c free() while the main scheduler of the primary + * execution stream is freed during \c ABT_finalize(). The detailed behavior of + * this routine will be clarified in the future. * * @contexts * \DOC_CONTEXT_FINALIZE \DOC_CONTEXT_CTXSWITCH diff --git a/src/include/abt.h.in b/src/include/abt.h.in index 8c7ecdcb5..4a9bc6431 100644 --- a/src/include/abt.h.in +++ b/src/include/abt.h.in @@ -33,7 +33,7 @@ extern "C" { * * \code{.unparsed} * ABT_VERSION = [MAJ].[MIN].[REV][EXT][EXT_NUMBER] - * Example: 1.0.7rc1 has + * Example: ABT_VERSION = 1.0.7rc1 represents * MAJ = 1 * MIN = 0 * REV = 7 @@ -62,8 +62,8 @@ extern "C" { * \endcode * * \c 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, so 1.0.7rc1 is converted to the - * numeric version 10007201. + * digit for EXT, and 2 digits for EXT_NUMBER. For example, 1.0.7rc1 is + * converted to the numeric version 10007201. */ #define ABT_NUMVERSION @ABT_NUMVERSION@ @@ -87,7 +87,7 @@ extern "C" { * @ingroup ERROR_CODE * @brief Error code: the routine returns successfully. * - * \c ABT_SUCCESS is guaranteed to have the value of zero. + * \c ABT_SUCCESS is guaranteed to be 0. */ #define ABT_SUCCESS 0 /** @@ -99,8 +99,7 @@ extern "C" { * @ingroup ERROR_CODE * @brief Error code: Memory allocation failure. * - * \c ABT_ERR_MEM is returned if memory allocation functions such as \c malloc() - * or \c mmap() fail. + * \c ABT_ERR_MEM is returned if memory allocation fails. */ #define ABT_ERR_MEM 2 /** @@ -110,17 +109,17 @@ extern "C" { #define ABT_ERR_OTHER 3 /** * @ingroup ERROR_CODE - * @brief Error code: invalid executions stream. + * @brief Error code: invalid execution stream. */ #define ABT_ERR_INV_XSTREAM 4 /** * @ingroup ERROR_CODE - * @brief Error code: invalid executions stream rank. + * @brief Error code: invalid execution stream rank. */ #define ABT_ERR_INV_XSTREAM_RANK 5 /** * @ingroup ERROR_CODE - * @brief Error code: invalid executions stream barrier. + * @brief Error code: invalid execution stream barrier. */ #define ABT_ERR_INV_XSTREAM_BARRIER 6 /** @@ -386,9 +385,10 @@ extern "C" { * * \c ABT_ERR_SYS represents a general error that happens in libraries used by * Argobots. For example, this error is returned when system calls such as - * \c futex() and \c open() or functions provided by standard libraries such as + * \c futex() and \c open() or functions provided by external libraries such as * \c pthread_create() and \c unw_init_local() fail. Note that \c ABT_ERR_MEM - * is returned if the error is caused by memory allocation. + * is returned if a memory allocation function such as \c malloc() or \c mmap() + * fails. */ #define ABT_ERR_SYS 54 /** @@ -458,9 +458,9 @@ enum ABT_sched_state { * @ingroup SCHED * @brief Predefined scheduler type. * - * Relying on a specific scheduling order is not recommended since its - * implementation can be changed. Users can create their own scheduler by using - * \c ABT_sched_create(). + * Relying on a specific scheduling order is not recommended since the + * implementation of predefined schedulers can be changed. Users can create + * their own scheduler by using \c ABT_sched_create(). */ enum ABT_sched_predef { /** Default scheduler. \c ABT_SCHED_BASIC is used. */ @@ -571,7 +571,7 @@ enum ABT_info_query_kind { ABT_INFO_QUERY_KIND_ENABLED_PRINT_ERRNO, /** Whether Argobots prints a debug message or not */ ABT_INFO_QUERY_KIND_ENABLED_LOG, - /** Whether Argobots is configured to be Valgrind friendly */ + /** Whether Argobots is configured to be Valgrind friendly or not */ ABT_INFO_QUERY_KIND_ENABLED_VALGRIND, /** Whether an error is checked or not */ ABT_INFO_QUERY_KIND_ENABLED_CHECK_ERROR, @@ -592,9 +592,10 @@ enum ABT_info_query_kind { ABT_INFO_QUERY_KIND_ENABLED_STACKABLE_SCHED, /** Whether the external thread feature is supported or not */ ABT_INFO_QUERY_KIND_ENABLED_EXTERNAL_THREAD, - /** Whether a predefined scheduler sleeps or not */ + /** Whether a predefined scheduler sleeps when idle or not */ ABT_INFO_QUERY_KIND_ENABLED_SCHED_SLEEP, - /** Whether the Argobots configuration is printed on ABT_init() or not */ + /** Whether the Argobots configuration is printed in the top-level + * ABT_init() or not */ ABT_INFO_QUERY_KIND_ENABLED_PRINT_CONFIG, /** Whether the affinity setting is supported or not */ ABT_INFO_QUERY_KIND_ENABLED_AFFINITY, @@ -627,13 +628,13 @@ enum ABT_info_query_kind { enum ABT_tool_query_kind { /** Query a pool to which a work unit is or will be pushed. */ ABT_TOOL_QUERY_KIND_POOL, - /** Query a current depth of stackable work units. */ + /** Query a current depth of stacked work units. */ ABT_TOOL_QUERY_KIND_STACK_DEPTH, - /** Query a type of caller that incurs an event. */ + /** Query a type of the caller that incurs an event. */ ABT_TOOL_QUERY_KIND_CALLER_TYPE, /** Query a handle to the caller that incurs an event. */ ABT_TOOL_QUERY_KIND_CALLER_HANDLE, - /** Query a type of synchronization object that incurs an event. */ + /** Query a type of the synchronization object that incurs an event. */ ABT_TOOL_QUERY_KIND_SYNC_OBJECT_TYPE, /** Query a handle of the synchronization object that incurs an event. */ ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE, @@ -661,7 +662,7 @@ enum ABT_sync_event_type { ABT_SYNC_EVENT_TYPE_USER, /** Other synchronization events. */ ABT_SYNC_EVENT_TYPE_OTHER, - /** Joining an executions stream. */ + /** Joining an execution stream. */ ABT_SYNC_EVENT_TYPE_XSTREAM_JOIN, /** Joining a work unit. */ ABT_SYNC_EVENT_TYPE_THREAD_JOIN, @@ -736,7 +737,7 @@ enum ABT_sync_event_type { #define ABT_TOOL_EVENT_THREAD_RESUME (1 << 9) /** * @ingroup TOOL - * @brief Work-unit-event mask: all events above. + * @brief Work-unit-event mask: all events. */ #define ABT_TOOL_EVENT_THREAD_ALL ((uint64_t)((1 << 12) - 1)) @@ -791,7 +792,7 @@ typedef struct ABT_xstream_opaque * ABT_xstream; typedef enum ABT_xstream_state ABT_xstream_state; /** * @ingroup ES_BARRIER - * @brief Execution stream barrier handle type. + * @brief Execution-stream barrier handle type. * * A NULL handle of this type is \c ABT_XSTREAM_BARRIER_NULL. */ @@ -823,7 +824,7 @@ typedef enum ABT_sched_predef ABT_sched_predef; * \DOC_V20 This type is removed since no Argobots routine uses this. * @endchangev20 */ -typedef enum ABT_sched_state ABT_sched_state ABT_DEPRECATED; +typedef enum ABT_sched_state ABT_sched_state; /** * @ingroup SCHED * @brief Scheduler's work unit type. @@ -1091,7 +1092,7 @@ typedef struct { * @ingroup MUTEX * @brief Initialize \c ABT_mutex_memory. * - * \c ABT_MUTEX_INITIALIZER() statically initializes \c ABT_mutex_memory. The + * \c ABT_MUTEX_INITIALIZER statically initializes \c ABT_mutex_memory. The * created mutex is not recursive. * The following shows how to use \c ABT_MUTEX_INITIALIZER. @@ -1106,12 +1107,7 @@ typedef struct { * } * @endcode * - * \c ABT_mutex obtained by \c ABT_MUTEX_MEMORY_GET_HANDLE() may not be freed by - * \c ABT_mutex_free(). The lifetime of \c ABT_mutex obtained by - * \c ABT_MUTEX_MEMORY_GET_HANDLE() is the same as that of \c ABT_mutex_memory. - * - * \c ABT_mutex_memory associated with the mutex that is in use may not be - * initialized. + * \c ABT_mutex_memory that is in use may not be initialized again. */ #define ABT_MUTEX_INITIALIZER \ { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } } @@ -1138,8 +1134,7 @@ typedef struct { * } * @endcode * - * \c ABT_mutex_memory associated with the mutex that is in use may not be - * initialized. + * \c ABT_mutex_memory that is in use may not be initialized again. */ #define ABT_RECURSIVE_MUTEX_INITIALIZER \ { { 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } } @@ -1180,7 +1175,7 @@ typedef struct { * @ingroup COND * @brief Initialize \c ABT_cond_memory. * - * \c ABT_COND_INITIALIZER() statically initializes \c ABT_cond_memory. + * \c ABT_COND_INITIALIZER statically initializes \c ABT_cond_memory. * The following example shows how to use \c ABT_COND_INITIALIZER. * @code{.c} @@ -1201,12 +1196,7 @@ typedef struct { * } * @endcode * - * \c ABT_cond obtained by \c ABT_COND_MEMORY_GET_HANDLE() may not be freed by - * \c ABT_cond_free(). The lifetime of \c ABT_cond obtained by - * \c ABT_COND_MEMORY_GET_HANDLE() is the same as that of \c ABT_cond_memory. - * - * \c ABT_cond_memory associated with a condition variable that is in use may - * not be initialized. + * \c ABT_cond_memory that is in use may not be initialized again. */ #define ABT_COND_INITIALIZER \ { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } } @@ -1267,9 +1257,9 @@ extern ABT_sched_config_var ABT_sched_config_var_end ABT_API_PUBLIC; * @var ABT_sched_basic_freq * @brief Predefined ABT_sched_config_var to configure the frequency for * checking events of the basic scheduler. + * @hideinitializer * * Its type is int. The user may not change its variables. - * @hideinitializer */ extern ABT_sched_config_var ABT_sched_basic_freq ABT_API_PUBLIC; /** @@ -1287,12 +1277,12 @@ extern ABT_sched_config_var ABT_sched_config_access ABT_API_PUBLIC; * @var ABT_sched_config_automatic * @brief Predefined ABT_sched_config_var to configure whether the scheduler * is freed automatically or not. + * @hideinitializer * * Its type is int. If the value is non-zero, the scheduler is freed * automatically after its associated objects are released. If the value is * zero, the scheduler is configured to be not freed automatically by the * Argobots runtime. The user may not change its variables. - * @hideinitializer */ extern ABT_sched_config_var ABT_sched_config_automatic ABT_API_PUBLIC; @@ -1436,9 +1426,9 @@ typedef struct { * @brief Access type. * * This value is used to determine a value returned by - * \c ABT_pool_get_access(). The Argobots assumes all pools can be accessed - * by any ULT, tasklet, or external thread. It is the user's responsibility - * to manage the access to pools. + * \c ABT_pool_get_access(). Argobots assumes all pools can be accessed by + * any ULTs, tasklets, and external threads. It is the user's + * responsibility to manage the access to pools. * * @changev11 * \DOC_DESC_V10_POOL_NOACCESS @@ -1538,8 +1528,9 @@ typedef struct { * * \c u_free() frees the work unit \c unit that is created by * \c u_create_from_thread(). Its associated entity (i.e., \c ABT_thread) - * is freed by the Argobots runtime. \c unit is neither pointing to - * \c ABT_UNIT_NULL nor \c NULL. The user may modify a value of \c unit. + * is freed by the Argobots runtime. Neither \c NULL nor a pointer pointing + * to \c ABT_UNIT_NULL is passed as \c unit to this function. \c u_free() + * may modify the value pointed to be \c unit. * * \c u_free() is not optional, so the user must implement this function. * @@ -1572,7 +1563,8 @@ typedef struct { * Specifically, the current Argobots treats a pool whose size is zero as an * empty pool. * - * \c u_free() is not optional, so the user must implement this function. + * \c p_get_size() is not optional, so the user must implement this + * function. * * The caller of \c p_get_size() is undefined, so a program that relies on * the caller of \c p_get_size() is non-conforming. @@ -1583,8 +1575,8 @@ typedef struct { * @brief Function that pushes a work unit to a pool. * * \c p_push() pushes the work unit \c unit to the pool \c pool. \c unit - * must be stored in \c pool and can be popped by its pop functions (e.g., - * \c p_pop()) later. + * must be stored in \c pool and able to be popped by its pop functions + * (e.g., \c p_pop()) later. * * \c p_push() is not optional, so the user must implement this function. * @@ -1644,8 +1636,8 @@ typedef struct { * on the caller of \c p_pop_timedwait() is non-conforming. * * @changev20 - * \DOC_V20 \c p_pop_timedwait() is deprecated. The user should use - * \c p_pop_wait() instead. + * \DOC_V20 \c p_pop_timedwait() is deprecated and replaced by + * \c p_pop_wait(). * @endchangev20 */ ABT_pool_pop_timedwait_fn p_pop_timedwait; @@ -1679,12 +1671,13 @@ typedef struct { /** * @fn int (*p_print_all)(ABT_pool pool, void *arg, * void (*print_f)(void *arg, ABT_unit unit)) - * @brief Function that applies a function to all work units in a pool. + * @brief Function that applies a user-given function to all work units in a + * pool. * * \c p_print_all() applies \c print_f to all work units in the pool * \c pool. \c print_f() is called with the user-given argument \c arg and - * the work unit. The caller guarantees that \c print_f() does not modify - * the state of \c pool and work units in \c pool. + * the work unit handle. The caller guarantees that \c print_f() does not + * modify the states of \c pool and work units in \c pool. * * \c p_print_all() is optional, so the user may set \c p_print_all to * \c NULL. diff --git a/src/info.c b/src/info.c index 8299a2c91..ff0d59172 100644 --- a/src/info.c +++ b/src/info.c @@ -22,7 +22,7 @@ static void info_trigger_print_all_thread_stacks( * \c ABT_info_query_config() returns the configuration information associated * with the query kind \c query_kind through \c val. * - * The retrieved information is selected by \c query_kind. + * The retrieved information is selected via \c query_kind. * * - \c ABT_INFO_QUERY_KIND_ENABLED_DEBUG * @@ -88,31 +88,32 @@ static void info_trigger_print_all_thread_stacks( * * \c val must be a pointer to a variable of type \c ABT_bool. \c val is set * to \c ABT_TRUE if Argobots is configured to enable the thread/task - * migration cancellation feature. Otherwise, \c val is set to \c ABT_FALSE. + * migration feature. Otherwise, \c val is set to \c ABT_FALSE. * * - \c ABT_INFO_QUERY_KIND_ENABLED_STACKABLE_SCHED * * \c val must be a pointer to a variable of type \c ABT_bool. \c val is set * to \c ABT_TRUE if Argobots is configured to enable the stackable scheduler - * feature is supported. Otherwise, \c val is set to \c ABT_FALSE. + * feature. Otherwise, \c val is set to \c ABT_FALSE. * * - \c ABT_INFO_QUERY_KIND_ENABLED_EXTERNAL_THREAD * * \c val must be a pointer to a variable of type \c ABT_bool. \c val is set * to \c ABT_TRUE if Argobots is configured to enable the external thread - * feature is supported. Otherwise, \c val is set to \c ABT_FALSE. + * feature. Otherwise, \c val is set to \c ABT_FALSE. * * - \c ABT_INFO_QUERY_KIND_ENABLED_SCHED_SLEEP * * \c val must be a pointer to a variable of type \c ABT_bool. \c val is set - * to \c ABT_TRUE if Argobots is configured to enable the sleep feature of + * to \c ABT_TRUE if Argobots is configured to enable the sleep feature for * predefined schedulers. Otherwise, \c val is set to \c ABT_FALSE. * * - \c ABT_INFO_QUERY_KIND_ENABLED_PRINT_CONFIG * * \c val must be a pointer to a variable of type \c ABT_bool. \c val is set * to \c ABT_TRUE if Argobots is configured to print all the configuration - * settings in \c ABT_init(). Otherwise, \c val is set to \c ABT_FALSE. + * settings in the top-level \c ABT_init(). Otherwise, \c val is set to + * \c ABT_FALSE. * * - \c ABT_INFO_QUERY_KIND_ENABLED_AFFINITY * @@ -123,8 +124,7 @@ static void info_trigger_print_all_thread_stacks( * - \c ABT_INFO_QUERY_KIND_MAX_NUM_XSTREAMS * * \c val must be a pointer to a variable of type \c unsigned \c int. \c val - * is set to the maximum number of execution streams that can be created by - * Argobots. + * is set to the maximum number of execution streams in Argobots. * * - \c ABT_INFO_QUERY_KIND_DEFAULT_THREAD_STACKSIZE * @@ -413,7 +413,7 @@ int ABT_info_print_config(FILE *fp) /** * @ingroup INFO - * @brief Print the information of execution streams. + * @brief Print the information of all execution streams. * * \c ABT_info_print_all_xstreams() writes the information of all execution * streams to the output stream \c fp. @@ -685,8 +685,8 @@ int ABT_info_print_thread_attr(FILE *fp, ABT_thread_attr attr) * @brief Print the information of a work unit. * * \c ABT_info_print_task() writes the information of the work unit \c task to - * the output stream \c fp. This routine is deprecated because this routine is - * the same as \c ABT_info_print_thread(). + * the output stream \c fp. This routine is deprecated because its + * functionality is the same as that of \c ABT_info_print_thread(). * * @note * \DOC_NOTE_INFO_PRINT @@ -730,8 +730,8 @@ int ABT_info_print_task(FILE *fp, ABT_task task) * @ingroup INFO * @brief Print stack of a work unit. * - * \c ABT_info_print_thread_stack() prints the stack of the work unit \c thread - * to the output stream \c fp. + * \c ABT_info_print_thread_stack() prints the information of the stack of the + * work unit \c thread to the output stream \c fp. * * @note * \DOC_NOTE_INFO_PRINT @@ -788,9 +788,9 @@ int ABT_info_print_thread_stack(FILE *fp, ABT_thread thread) * @ingroup INFO * @brief Print stacks of all work units in a pool. * - * \c ABT_info_print_thread_stacks_in_pool() prints stacks of all work units in - * the pool \c pool to the output stream \c fp. \c pool must support - * \c p_print_all() to check all work units in the pool. + * \c ABT_info_print_thread_stacks_in_pool() prints the information of stacks of + * all work units in the pool \c pool to the output stream \c fp. \c pool must + * support \c p_print_all(). * * @note * \DOC_NOTE_INFO_PRINT @@ -833,24 +833,29 @@ int ABT_info_print_thread_stacks_in_pool(FILE *fp, ABT_pool pool) * @brief Print stacks of work units in pools associated with all the main * schedulers. * - * \c ABT_info_trigger_print_all_thread_stacks() tries to print stacks of all - * threads stored in pools associated with all the main schedulers to the output - * stream \c fp. This routine itself does not print stacks; it immediately - * returns after updating a flag. Stacks are printed when all execution streams - * stop in \c ABT_xstream_check_events(). - * - * If some execution streams do not stop within a certain time period specified - * by \c timeout in seconds where \c timeout is not negative, one of the - * execution streams that stop at \c ABT_xstream_check_events() starts to print - * the stack information. In this case, this routine might not work correctly - * and at worst crashes a program. This routine does not work at all if no - * execution stream executes \c ABT_xstream_check_events(). + * \c 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 \c 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 + * \c ABT_xstream_check_events(). + * + * If \c timeout is negative, the stack information is printed only after all + * the execution streams stop at \c ABT_xstream_check_events(). If \c timeout + * is nonnegative, one of the execution streams that stop at + * \c ABT_xstream_check_events() starts to print the stack information even if + * some of the execution streams do not stop at \c ABT_xstream_check_events() + * within a certain time period specified by \c 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 + * \c ABT_xstream_check_events(). * * The callback function \c cb_func() is called after completing printing stacks - * unless \c cb_func is \c NULL. The first argument is set to \c ABT_TRUE if - * not all the execution streams stop within \c timeout. Otherwise, - * \c ABT_FALSE is passed. The second argument is the user-defined data \c arg - * passed to this routine. The caller of \c cb_func() is undefined, so a + * unless it is registered. The first argument of \c cb_func() is set to + * \c ABT_TRUE if \c timeout is nonnegative and not all the execution streams + * stop within \c timeout. Otherwise, the first argument is set to + * \c ABT_FALSE. The second argument of \c cb_func() is the user-defined data + * \c arg passed to this routine. The caller of \c cb_func() is undefined, so a * program that relies on the caller of \c cb_func() is non-conforming. Neither * signal-safety nor thread-safety is required for \c cb_func(). * diff --git a/src/key.c b/src/key.c index 0fb7c52a8..8037525ce 100644 --- a/src/key.c +++ b/src/key.c @@ -5,8 +5,8 @@ #include "abti.h" -/** @defgroup KEY Work-Unit Local Storage - * This group is for work-unit specific data, which can be described as +/** @defgroup KEY Work-Unit-Specific Data + * This group is for work-unit-specific data, which can be described as * work-unit local storage (which is similar to "thread-local storage" or TLS). */ @@ -26,7 +26,7 @@ static ABTD_atomic_uint32 g_key_id = * existing work units. Upon work-unit creation, the value \c NULL will be * associated with all the defined keys in the new work unit. * - * An optional destructor function \c destructor() may be associated with + * An optional destructor function \c destructor() may be registered to * \c newkey. When a work unit is freed, if a key has a non-\c NULL destructor * and the work unit has a non-\c NULL value associated with that key, the value * of the key is set to \c NULL, and then \c destructor() is called with the @@ -43,8 +43,8 @@ static ABTD_atomic_uint32 g_key_id = * is not called by the associated work-unit, so a program that relies on a * caller of \c destructor() is non-conforming. * - * \c destructor() is called even if the associated key has been freed by - * \c ABT_key_free(). + * \c destructor() is called even if the associated key has already been freed + * by \c ABT_key_free(). * * The created key must be freed by \c ABT_key_free() after its use. * @@ -81,14 +81,15 @@ int ABT_key_create(void (*destructor)(void *value), ABT_key *newkey) * @brief Free a work-unit-specific data key. * * \c ABT_key_free() deallocates the resource used for the work-unit-specific - * data key \c key and sets \c key to \c ABT_KEY_NULL. It is the user's - * responsibility to free memory for values associated with the deleted key. + * data key \c key and sets \c key to \c ABT_KEY_NULL. + * + * It is the user's responsibility to free memory for values associated with the + * deleted key. * * The user is allowed to delete a key before terminating all work units that * have non-\c NULL values associated with \c key. The user cannot refer to a - * value via the deleted key, but the destructor of the deleted key will be - * called when a work unit that has a non-\c NULL value associated with that key - * is freed. + * value via the deleted key, but the destructor of the deleted key is called + * when a work unit is freed. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH @@ -119,17 +120,17 @@ int ABT_key_free(ABT_key *key) /** * @ingroup KEY - * @brief Associate a value with a work-unit-specific key in the calling work - * unit. + * @brief Associate a value with a work-unit-specific data key in the calling + * work unit. * - * \c ABT_key_set() associates a value \c value of the work-unit-specific data - * key \c key in the calling work unit. Different work units may bind different + * \c ABT_key_set() associates a value \c value with the work-unit-specific data + * key \c key in the calling work unit. Different work units may bind different * values to the same key. * * \DOC_DESC_ATOMICITY_WORK_UNIT_KEY * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_set_specific()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_set_specific()} * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED @@ -173,17 +174,18 @@ int ABT_key_set(ABT_key key, void *value) /** * @ingroup KEY - * @brief Get a value associated with a key in the calling work unit. + * @brief Get a value associated with a work-unit-specific data key in the + * calling work unit. * * \c ABT_key_get() returns the value in the caller associated with the * work-unit-specific data key \c key in the calling work unit through \c value. - * If the caller has never set a value for the key, this routine sets \c value + * If the caller has never set a value for \c key, this routine sets \c value * to \c NULL. * * \DOC_DESC_ATOMICITY_WORK_UNIT_KEY * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_get_specific()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_get_specific()} * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED diff --git a/src/mutex.c b/src/mutex.c index bae97b6b8..f90267cda 100644 --- a/src/mutex.c +++ b/src/mutex.c @@ -161,11 +161,11 @@ int ABT_mutex_free(ABT_mutex *mutex) * * \c ABT_mutex_lock() locks the mutex \c mutex. If this routine successfully * returns, the caller acquires \c mutex. If \c mutex has already been locked, - * the caller will be blocked on \c mutex until \c mutex becomes available. + * the caller is blocked on \c mutex until \c mutex becomes available. * * If \c mutex is recursive, the same caller can acquire multiple levels of - * ownership over \c mutex. \c mutex will remain locked until \c mutex is - * unlocked as many times as the level of ownership. + * ownership over \c mutex. \c mutex remains locked until \c mutex is unlocked + * as many times as the level of ownership. * * @contexts * \DOC_CONTEXT_ANY \DOC_CONTEXT_CTXSWITCH_CONDITIONAL{\c mutex is locked and @@ -225,7 +225,7 @@ int ABT_mutex_lock_low(ABT_mutex mutex) * @ingroup MUTEX * @brief Lock a mutex with high priority. * - * \c ABT_mutex_lock_low() locks the mutex \c mutex with high priority while + * \c ABT_mutex_lock_high() locks the mutex \c mutex with high priority while * \c ABT_mutex_lock() and \c ABT_mutex_lock_low() do with lower priority. That * is, waiters that call the high-priority mutex lock functions might be * prioritized over the same \c mutex. Except for priority, the semantics of @@ -264,8 +264,8 @@ int ABT_mutex_lock_high(ABT_mutex mutex) * to take a lock, \c ABT_ERR_MUTEX_LOCKED is returned. * * If \c mutex is recursive, the same caller can acquire multiple levels of - * ownership over \c mutex. \c mutex will remain locked until \c mutex is - * unlocked as many times as the level of ownership. + * ownership over \c mutex. \c mutex remains locked until \c mutex is unlocked + * as many times as the level of ownership. * * This trylock operation is atomically strong, so lock acquisition by this * routine never fails if \c mutex is not locked. @@ -293,23 +293,23 @@ int ABT_mutex_trylock(ABT_mutex mutex) /** * @ingroup MUTEX - * @brief Lock a mutex in a busy-wait loop. + * @brief Lock a mutex in a busy-wait form. * - * \c ABT_mutex_spinlock() locks the mutex \c mutex in a blocking form. If this - * routine successfully returns, the caller acquires \c mutex. If \c mutex has - * already been locked, the caller will be blocked on \c mutex until \c mutex + * \c ABT_mutex_spinlock() locks the mutex \c mutex in a busy-wait form. If + * this routine successfully returns, the caller acquires \c mutex. If \c mutex + * has already been locked, the caller is blocked on \c mutex until \c mutex * becomes available. * * If \c mutex is recursive, the same caller can acquire multiple levels of - * ownership over \c mutex. \c mutex will remain locked until \c mutex is - * unlocked as many times as the level of ownership. + * ownership over \c mutex. \c mutex remain locked until \c mutex is unlocked + * as many times as the level of ownership. * * @note * \c ABT_mutex_spinlock() might show a slightly better performance than * \c ABT_mutex_lock() if \c mutex is uncontended. This routine, however, - * blocks the underlying execution stream when \c mutex is locked even if the - * caller is a ULT. This blocking behavior is deadlock-prone, so the user must - * be cautious when using this routine. + * blocks the underlying execution stream when \c mutex has already been locked + * even if the caller is a ULT. This busy-wait behavior is deadlock-prone, so + * the user should carefully use this routine. * * @contexts * \DOC_CONTEXT_ANY \DOC_CONTEXT_NOCTXSWITCH @@ -458,8 +458,8 @@ int ABT_mutex_unlock_de(ABT_mutex mutex) * \c ABT_mutex_equal() compares two mutex handles \c mutex1 and \c mutex2 for * equality and returns the result through \c result. * - * This function is deprecated since its behavior is the same as comparing - * values of \c mutex1 and \c mutex2. + * This routine is deprecated since its behavior is the same as comparing values + * of \c mutex1 and \c mutex2. * @code{.c} * *result = (mutex1 == mutex2) ? ABT_TRUE : ABT_FALSE; * @endcode @@ -491,10 +491,9 @@ int ABT_mutex_equal(ABT_mutex mutex1, ABT_mutex mutex2, ABT_bool *result) * @brief Get attributes of a mutex. * * \c ABT_mutex_get_attr() returns a newly created attribute object that is - * copied from the attributes of the mutex \c mutex through \c attr. Attribute - * values of \c attr may be different from those used on the creation of - * \c mutex. Since this routine allocates a mutex attribute object, it is the - * user's responsibility to free \c attr after its use. + * copied from the attributes of the mutex \c mutex through \c attr. Since this + * routine allocates a mutex attribute object, it is the user's responsibility + * to free \c attr after its use. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH diff --git a/src/mutex_attr.c b/src/mutex_attr.c index a48cb058b..79739f54c 100644 --- a/src/mutex_attr.c +++ b/src/mutex_attr.c @@ -6,8 +6,8 @@ #include "abti.h" /** @defgroup MUTEX_ATTR Mutex Attributes - * Mutex attributes are used to specify mutex behavior that is different from - * the default. + * This group is for Mutex Attributes. Mutex attributes are used to specify + * mutex behavior that is different from the default. */ /** diff --git a/src/pool/pool.c b/src/pool/pool.c index e9fb8d07f..f0f956f5f 100644 --- a/src/pool/pool.c +++ b/src/pool/pool.c @@ -23,8 +23,8 @@ ABTU_ret_err static int pool_create(ABTI_pool_def *def, ABT_pool_config config, * routine returns an error returned by \c p_init() if \c p_init() does not * return \c ABT_SUCCESS. * - * The user can pass \c ABT_POOL_CONFIG_NULL as \c config. The configuration is - * passed as the parameter of the initialization function of the pool. + * \c config is passed as the second argument of the initialization function of + * the pool. * * \c def must define all the non-optional functions. See \c #ABT_pool_def for * details. @@ -266,7 +266,7 @@ int ABT_pool_get_access(ABT_pool pool, ABT_pool_access *access) * - If \c pool is created by \c ABT_pool_create_basic(): * * This routine sets \c size to the sum of the number of work units including - * in \c pool and the number of blocking work units associated with \c pool. + * works units in \c pool and suspended work units associated with \c pool. * * @changev11 * \DOC_DESC_V10_ACCESS_VIOLATION @@ -355,8 +355,8 @@ int ABT_pool_get_size(ABT_pool pool, size_t *size) * * This routine tries to pop a work unit from \c pool. If this routine * successfully pops a work unit, this routine sets \c p_unit to the obtained - * handle of \c ABT_unit. Otherwise, this routine sets \c ABT_UNIT_NULL to - * \c p_unit. + * handle of \c ABT_unit. Otherwise, this routine sets \c p_unit to + * \c ABT_UNIT_NULL. * * @changev11 * \DOC_DESC_V10_ACCESS_VIOLATION @@ -416,8 +416,8 @@ int ABT_pool_pop(ABT_pool pool, ABT_unit *p_unit) * * @note * In most cases, \c ABT_pool_pop() is more efficient. \c ABT_pool_pop_wait() - * would be useful in cases where the user wants to make execution streams sleep - * when \c pool is empty. + * would be useful in cases where the user wants to sleep execution streams when + * \c pool is empty. * * @changev20 * \DOC_DESC_V1X_P_POP_WAIT @@ -462,7 +462,7 @@ int ABT_pool_pop_wait(ABT_pool pool, ABT_unit *p_unit, double time_secs) * - If \c pool is created by \c ABT_pool_create(): * * This routine sets \c p_unit to a value returned by \c p_pop_timedwait() - * called with \c pool as its first argument and \c abstime_sec as the second + * called with \c pool as its first argument and \c abstime_secs as the second * argument. * * - If \c pool is created by \c ABT_pool_create_basic(): @@ -472,14 +472,12 @@ int ABT_pool_pop_wait(ABT_pool pool, ABT_unit *p_unit, double time_secs) * routine is blocked on \c pool until the current time exceeds * \c abstime_secs. If this routine successfully pops a work unit, this * routine sets \c p_unit to the obtained handle of \c ABT_unit. Otherwise, - * this routine sets \c ABT_UNIT_NULL to \c p_unit. + * this routine sets \c p_unit to \c ABT_UNIT_NULL. * * @note * \c abstime_secs can be calculated by adding an offset time to a value - * returned by \c ABT_get_wtime(). - * - * This routine is deprecated. The user should use \c ABT_pool_pop_wait() - * instead. + * returned by \c ABT_get_wtime().\n + * \DOC_NOTE_REPLACEMENT{\c ABT_pool_pop_wait()}. * * @changev11 * \DOC_DESC_V10_ACCESS_VIOLATION @@ -708,10 +706,10 @@ int ABT_pool_set_data(ABT_pool pool, void *data) * @ingroup POOL * @brief Retrieve user data from a pool * - * \c ABT_pool_set_data() returns user data in the pool \c pool through \c data. + * \c ABT_pool_get_data() returns user data in the pool \c pool through \c data. * * @note - * The specific data of the newly created pool is \c NULL. + * The user data of the newly created pool is \c NULL. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH diff --git a/src/rwlock.c b/src/rwlock.c index 7ef4e409d..bfeb3c0fd 100644 --- a/src/rwlock.c +++ b/src/rwlock.c @@ -13,6 +13,7 @@ /** * @ingroup RWLOCK * @brief Create a new readers-writer lock. + * * \c ABT_rwlock_create() creates a new readers-writer lock and returns its * handle through \c newrwlock. * @@ -103,8 +104,8 @@ int ABT_rwlock_free(ABT_rwlock *rwlock) * * \c ABT_rwlock_rdlock() locks the readers-writer lock \c rwlock as a reader. * If this routine successfully returns, the caller acquires \c rwlock. If - * \c rwlock has been locked by a writer, the caller will be blocked on - * \c rwlock until \c rwlock becomes available. + * \c rwlock has been locked by a writer, the caller is blocked on \c rwlock + * until \c rwlock becomes available. * * \c rwlock may be acquired by multiple readers. * @@ -114,7 +115,7 @@ int ABT_rwlock_free(ABT_rwlock *rwlock) * \c ABT_rwlock_rdlock()) to make \c rwlock available to a writer. * * @changev20 - * \DOC_DESC_V1X_NOTASK{\c rwlock} + * \DOC_DESC_V1X_NOTASK{\c ABT_ERR_RWLOCK} * @endchangev20 * * @contexts @@ -169,13 +170,13 @@ int ABT_rwlock_rdlock(ABT_rwlock rwlock) * * \c ABT_rwlock_wrlock() locks the readers-writer lock \c rwlock as a writer. * If this routine successfully returns, the caller acquires \c rwlock. If - * \c rwlock has been locked by either a reader or a writer, the caller will be - * blocked on \c rwlock until \c rwlock becomes available. + * \c rwlock has been locked by either a reader or another writer, the caller + * is blocked on \c rwlock until \c rwlock becomes available. * - * \c rwlock may be acquired by a single writer. + * \c rwlock may be acquired by only a single writer. * * @changev20 - * \DOC_DESC_V1X_NOTASK{\c rwlock} + * \DOC_DESC_V1X_NOTASK{\c ABT_ERR_RWLOCK} * @endchangev20 * * @contexts @@ -231,6 +232,9 @@ int ABT_rwlock_wrlock(ABT_rwlock rwlock) * * \c ABT_rwlock_unlock() unlocks the readers-writer lock \c rwlock. * + * @note + * Both readers and a writer can call this routine to unlock \c rwlock. + * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_CTXSWITCH_CONDITIONAL{a waiter is waiting on * \c mutex} diff --git a/src/sched/config.c b/src/sched/config.c index ecc641086..68e6600ee 100644 --- a/src/sched/config.c +++ b/src/sched/config.c @@ -45,13 +45,13 @@ ABT_sched_config_var ABT_sched_basic_freq = { .idx = -4, * \c ABT_sched_config_var and a value for this variable. The array must end * with a single value \c ABT_sched_config_var_end. * - * The current Argobots supports the following hints: + * Currently, Argobots supports the following hints: * * - \c ABT_sched_basic_freq: * * The frequency of event checks of the predefined scheduler. A smaller value - * indicates a more frequent check. If this is not specified, the default - * value is used for scheduler creation. + * indicates more frequent check. If this is not specified, the default value + * is used for scheduler creation. * * - \c ABT_sched_config_automatic: * @@ -80,7 +80,7 @@ ABT_sched_config_var ABT_sched_basic_freq = { .idx = -4, * @endcode * * If the array contains multiple tuples that have the same \c idx of - * \c ABT_sched_config_var, the value associated with \c idx is corrupted. + * \c ABT_sched_config_var, \c idx is mapped to a corrupted value. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH @@ -172,10 +172,10 @@ int ABT_sched_config_create(ABT_sched_config *config, ...) * \c idx = \a i does not exist, the \a i th argument is not updated. * * @note - * For example, this routine can be called as follows to get a value is - * corresponding to \c ABT_sched_config_var where its \c idx is 1. + * For example, this routine can be called as follows to get a value that is + * corresponding to \c idx = \a 1. * @code{.c} - * ABT_sched_config_var var = { 1, ABT_SCHED_CONFIG_INT }; + * // ABT_sched_config_var var = { 1, ABT_SCHED_CONFIG_INT }; * int val; * ABT_sched_config_read(&config, 2, NULL, &val); * @endcode diff --git a/src/sched/sched.c b/src/sched/sched.c index e2c5971d7..b1be4185e 100644 --- a/src/sched/sched.c +++ b/src/sched/sched.c @@ -30,10 +30,6 @@ static inline uint64_t sched_get_new_id(void); * \c def must define all non-optional functions. See \c #ABT_sched_def for * details. * - * @note - * Specifically, any explicit or implicit yielding operation in scheduling - * functions except for \c run() causes undefined behavior. - * * \c newsched is associated with the array of pools \c pools, which has * \c num_pools \c ABT_pool handles. If the \a i th element of \c pools is * \c ABT_POOL_NULL, the default FIFO pool with the default pool configuration @@ -53,12 +49,11 @@ static inline uint64_t sched_get_new_id(void); * @note * \DOC_NOTE_DEFAULT_SCHED_CONFIG * - * \c def, \c config, and the contents of \c pools are copied in this routine, - * so the user can free \c def, \c config, and \c pools after this routine - * returns. + * This routine copies \c def, \c config, and the contents of \c pools, so the + * user can free \c def, \c config, and \c pools after this routine returns. * * \DOC_DESC_SCHED_AUTOMATIC{\c newsched} By default \c newsched created by this - * routine is not automatically freed unless \c config enables it. + * routine is not automatically freed. * * @note * \DOC_NOTE_EFFECT_ABT_FINALIZE @@ -141,7 +136,7 @@ int ABT_sched_create(ABT_sched_def *def, int num_pools, ABT_pool *pools, * unexpected behavior caused by automatically created pools. * * \c newsched can be configured via \c config. If the user passes - * \c ABT_CONFIG_NULL for \c config, the default configuration is used. + * \c ABT_CONFIG_NULL as \c config, the default configuration is used. * * @note * \DOC_NOTE_DEFAULT_SCHED_CONFIG @@ -428,8 +423,8 @@ int ABT_sched_exit(ABT_sched sched) * \c ABT_sched_has_to_stop() checks if the scheduler \c sched needs to stop * with respect to the finish request and returns its value through \c stop. If * \c sched needs to stop, \c stop is set to \c ABT_TRUE. Otherwise, \c stop is - * set to \c ABT_FALSE. If \c sched is not running, \c stop is either set to an - * undefined value or not updated. + * set to \c ABT_FALSE. If \c sched is not running, \c stop is set to an + * undefined value. * * If \c sched is created by \c ABT_sched_create(), it is the user's * responsibility to take proper measures to stop \c sched when \c stop is set diff --git a/src/self.c b/src/self.c index 24189da28..bdef44467 100644 --- a/src/self.c +++ b/src/self.c @@ -24,7 +24,6 @@ * \DOC_ERROR_INV_XSTREAM_EXT * * @undefined - * \DOC_UNDEFINED_UNINIT * \DOC_UNDEFINED_NULL_PTR{\c xstream} * \DOC_UNDEFINED_UNINIT * @@ -57,7 +56,6 @@ int ABT_self_get_xstream(ABT_xstream *xstream) * \DOC_ERROR_INV_XSTREAM_EXT * * @undefined - * \DOC_UNDEFINED_UNINIT * \DOC_UNDEFINED_NULL_PTR{\c rank} * \DOC_UNDEFINED_UNINIT * @@ -153,11 +151,11 @@ int ABT_self_get_task_id(ABT_unit_id *id); /** * @ingroup SELF - * @brief Associate a value with a work-unit-specific key in the calling work - * unit. + * @brief Associate a value with a work-unit-specific data key in the calling + * work unit. * - * \c ABT_self_set_specific() associates a value \c value of the - * work-unit-specific data key \c key in the calling work unit. Different work + * \c ABT_self_set_specific() associates a value \c value with the + * work-unit-specific data key \c key in the calling work unit. Different work * units may bind different values to the same key. * * \DOC_DESC_ATOMICITY_WORK_UNIT_KEY @@ -199,11 +197,12 @@ int ABT_self_set_specific(ABT_key key, void *value) /** * @ingroup SELF - * @brief Get a value associated with a key in the calling work unit. + * @brief Get a value associated with a work-unit-specific data key in the + * calling work unit. * * \c ABT_self_get_specific() returns the value in the caller associated with * the work-unit-specific data key \c key in the calling work unit through - * \c value. If the caller has never set a value for the key, this routine sets + * \c value. If the caller has never set a value for \c key, this routine sets * \c value to \c NULL. * * \DOC_DESC_ATOMICITY_WORK_UNIT_KEY @@ -497,9 +496,9 @@ int ABT_self_yield(void) * @brief Suspend the calling ULT. * * \c ABT_self_suspend() suspends the execution of the calling ULT and switches - * to its parent ULT. The caller ULT is not pushed to its associated pool and - * its state becomes blocked. The suspended ULT can be awakened and pushed back - * to its associated pool when \c ABT_thread_resume() is called. + * to its parent ULT. The calling ULT is not pushed to its associated pool and + * its state becomes blocked. \c ABT_thread_resume() awakens the suspended ULT + * and pushes it back to its associated pool. * * @changev11 * \DOC_DESC_V10_ERROR_CODE_CHANGE{\c ABT_ERR_INV_THREAD, @@ -546,7 +545,7 @@ int ABT_self_suspend(void) * @errors * \DOC_ERROR_INV_XSTREAM_EXT * \DOC_ERROR_INV_THREAD_NY - * \DOC_ERROR_INV_THREAD_PRIMARY_ULT{\c the caller} + * \DOC_ERROR_INV_THREAD_PRIMARY_ULT{the caller} * * @undefined * \DOC_UNDEFINED_UNINIT @@ -569,11 +568,11 @@ int ABT_self_exit(void) * @ingroup SELF * @brief Set an argument for a work-unit function of the calling work unit * - * \c ABT_self_set_arg() sets the argument \c arg for the caller's work unit + * \c ABT_self_set_arg() sets the argument \c arg for the caller's work-unit * function. * * @note - * The newly set argument will be used if the caller is revived. + * The new argument will be used if the calling work unit is revived. * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED @@ -608,11 +607,11 @@ int ABT_self_set_arg(void *arg) /** * @ingroup SELF - * @brief Retrieve an argument for a work unit function of the calling work + * @brief Retrieve an argument for a work-unit function of the calling work * unit * - * \c ABT_self_get_arg() returns the argument for the caller's work unit - * function. + * \c ABT_self_get_arg() returns the argument that is passed to the caller's + * work-unit function through \c arg. * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED @@ -652,10 +651,10 @@ int ABT_self_get_arg(void **arg) * @ingroup SELF * @brief Check if the calling work unit is unnamed * - * \c ABT_self_is_unnamed() checks if the current caller is unnamed and returns - * the result through \c is_unnamed. \c is_unnamed is set to \c ABT_TRUE if the - * calling work unit is unnamed. Otherwise, \c is_unnamed is set to \c - * ABT_FALSE. + * \c ABT_self_is_unnamed() checks if the calling work unit is unnamed and + * returns the result through \c is_unnamed. \c is_unnamed is set to + * \c ABT_TRUE if the calling work unit is unnamed. Otherwise, \c is_unnamed is + * set to \c ABT_FALSE. * * @contexts * \DOC_CONTEXT_INIT_NOEXT \DOC_CONTEXT_NOCTXSWITCH diff --git a/src/stream.c b/src/stream.c index eaa476cb1..440a739a7 100644 --- a/src/stream.c +++ b/src/stream.c @@ -230,7 +230,7 @@ int ABT_xstream_create_basic(ABT_sched_predef predef, int num_pools, * \c newxstream is freed. * * This routine allocates the rank \c rank for \c newxstream. \c rank must be - * non-negative value and unique among all the execution streams. + * non-negative and not used by another execution stream. * * \DOC_DESC_ATOMICITY_RANK * @@ -317,7 +317,7 @@ int ABT_xstream_create_with_rank(ABT_sched sched, int rank, * \DOC_DESC_ATOMICITY_XSTREAM_STATE * * \c xstream may not be an execution stream that has been freed by - * \c ABT_xstream_free(). An execution stream that is blocked on by + * \c ABT_xstream_free(). An execution stream that is blocked on by a caller of * \c ABT_xstream_free() may not be revived. * * @contexts @@ -402,7 +402,7 @@ int ABT_xstream_revive(ABT_xstream xstream) * @undefined * \DOC_UNDEFINED_UNINIT * \DOC_UNDEFINED_NULL_PTR{\c xstream} - * \DOC_UNDEFINED_XSTREAM_BLOCKED{\c xstream, \c ABT_xstream_join() and + * \DOC_UNDEFINED_XSTREAM_BLOCKED{\c xstream, \c ABT_xstream_join() or * \c ABT_xstream_free()} * \DOC_UNDEFINED_THREAD_UNSAFE_FREE{\c xstream} * @@ -466,7 +466,7 @@ int ABT_xstream_free(ABT_xstream *xstream) * * @undefined * \DOC_UNDEFINED_UNINIT - * \DOC_UNDEFINED_XSTREAM_BLOCKED{\c xstream, \c ABT_xstream_join() and + * \DOC_UNDEFINED_XSTREAM_BLOCKED{\c xstream, \c ABT_xstream_join() or * \c ABT_xstream_free()} * \DOC_UNDEFINED_THREAD_UNSAFE{\c xstream} * @@ -495,19 +495,20 @@ int ABT_xstream_join(ABT_xstream xstream) * * \DOC_DESC_ATOMICITY_XSTREAM_REQUEST * + * @note + * \DOC_NOTE_TIMING_REQUEST + * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED * @endchangev20 * - * @note - * \DOC_NOTE_TIMING_REQUEST - * * @contexts * \DOC_CONTEXT_INIT_YIELDABLE \DOC_CONTEXT_CTXSWITCH * * @errors - * \DOC_ERROR_INV_XSTREAM_EXT * \DOC_ERROR_INV_THREAD_NY + * \DOC_ERROR_INV_THREAD_PRIMARY_ULT{the caller} + * \DOC_ERROR_INV_XSTREAM_EXT * \DOC_ERROR_INV_XSTREAM_PRIMARY{an execution stream that is running the * calling ULT} * \DOC_V1X \DOC_ERROR_UNINITIALIZED @@ -525,7 +526,7 @@ int ABT_xstream_exit(void) ABTI_SETUP_GLOBAL(NULL); #endif ABTI_SETUP_LOCAL_YTHREAD(&p_local_xstream, &p_ythread); - /* Check if the target is the primary executions stream. */ + /* Check if the target is the primary execution stream. */ ABTI_CHECK_TRUE(p_local_xstream->type != ABTI_XSTREAM_TYPE_PRIMARY, ABT_ERR_INV_XSTREAM); @@ -589,7 +590,7 @@ int ABT_xstream_cancel(ABT_xstream xstream) * running the calling work unit through \c xstream. * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_get_xstream()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_get_xstream()} * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED @@ -606,7 +607,6 @@ int ABT_xstream_cancel(ABT_xstream xstream) * \DOC_V1X \DOC_ERROR_UNINITIALIZED * * @undefined - * \DOC_UNDEFINED_UNINIT * \DOC_UNDEFINED_NULL_PTR{\c xstream} * \DOC_V20 \DOC_UNDEFINED_UNINIT * @@ -635,7 +635,7 @@ int ABT_xstream_self(ABT_xstream *xstream) * running the calling work unit through \c rank. * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_get_xstream_rank()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_get_xstream_rank()} * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED @@ -650,7 +650,6 @@ int ABT_xstream_self(ABT_xstream *xstream) * \DOC_V1X \DOC_ERROR_UNINITIALIZED * * @undefined - * \DOC_UNDEFINED_UNINIT * \DOC_UNDEFINED_NULL_PTR{\c rank} * \DOC_V20 \DOC_UNDEFINED_UNINIT * @@ -677,11 +676,11 @@ int ABT_xstream_self_rank(int *rank) * the execution stream \c xstream. The original rank of \c xstream is * deallocated. * - * \c rank must be non-negative and unique among all the execution streams. + * \c rank must be non-negative and not used by another execution stream. * * \DOC_DESC_ATOMICITY_RANK * - * The primary execution stream cannot change its rank. + * The rank of the primary execution stream may not be changed. * * @note * If the affinity setting is enabled, this routine updates the CPU binding of @@ -790,7 +789,7 @@ int ABT_xstream_get_rank(ABT_xstream xstream, int *rank) * \DOC_NOTE_DEFAULT_SCHED_CONFIG * * @changev11 - * \DOC_DESC_V10_CRUDE_SCHED_SIZE_CHECK{\c xstream, \c ABT_ERR_XSTREAM} + * \DOC_DESC_V10_INCOMPLETE_SCHED_SIZE_CHECK{\c xstream, \c ABT_ERR_XSTREAM} * * \DOC_DESC_V10_ACCESS_VIOLATION * @endchangev11 @@ -1172,7 +1171,7 @@ int ABT_xstream_is_primary(ABT_xstream xstream, ABT_bool *is_primary) * @ingroup ES * @brief Execute a work unit. * - * \c ABT_xstream_run_unit() runs a work unit \c unit associated with the pool + * \c ABT_xstream_run_unit() runs the work unit \c unit associated with the pool * \c pool as a child ULT on the calling ULT, which becomes a parent ULT. The * calling ULT will be resumed when \c unit finishes or yields. * @@ -1215,14 +1214,11 @@ int ABT_xstream_run_unit(ABT_unit unit, ABT_pool pool) * @brief Process events associated with a scheduler * * \c ABT_xstream_check_events() processes events associated with the scheduler - * \c sched. The calling work unit must be associated with the scheduler - * \c sched. - * - * This routine must be called by a scheduler periodically. + * \c sched. The calling work unit must be associated with \c sched. * - * @note - * For example, a user-defined scheduler should call this routine every hundred - * iterations of its scheduling loop. + * This routine must be called by a scheduler periodically. For example, a + * user-defined scheduler should call this routine every N iterations of its + * scheduling loop. * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED @@ -1310,7 +1306,7 @@ int ABT_xstream_set_cpubind(ABT_xstream xstream, int cpuid) * * \c ABT_xstream_get_cpubind() returns the CPU ID of a CPU to which the * execution stream \c xstream is bound through \c cpuid. If \c xstream is - * bound to more than one CPU, one of the CPU IDs is set to \c cpuid. + * bound to more than one CPU, \c cpuid is set to one of the CPU IDs. * * @note * \DOC_NOTE_CPUID diff --git a/src/stream_barrier.c b/src/stream_barrier.c index fc0f5aeef..90a2b2b32 100644 --- a/src/stream_barrier.c +++ b/src/stream_barrier.c @@ -15,8 +15,8 @@ * * \c ABT_xstream_barrier_create() creates a new execution-stream barrier and * returns its handle through \c newbarrier. \c num_waiters specifies the - * number of waiters that must call \c ABT_xstream_barrier_create() before any - * of the waiters successfully return from the call. \c num_waiters must be + * number of waiters that must call \c ABT_xstream_barrier_wait() before any of + * the waiters successfully return from the call. \c num_waiters must be * greater than zero. * * \c newbarrier must be freed by \c ABT_xstream_barrier_free() after its use. diff --git a/src/task.c b/src/task.c index 37c39f5e9..d9ea6bcc8 100644 --- a/src/task.c +++ b/src/task.c @@ -11,19 +11,19 @@ ABTU_ret_err static int task_create(ABTI_local *p_local, ABTI_pool *p_pool, ABTI_thread **pp_newtask); /** @defgroup TASK Tasklet - * This group is for Tasklet. + * This group is for Tasklet. A tasklet is a work unit that cannot yield. */ /** * @ingroup TASK - * @brief Create a new task. + * @brief Create a new tasklet. * * \c ABT_task_create() creates a new tasklet, associates it with the pool * \c pool, and returns its handle through \c newtask. This routine pushes the * created tasklet to the pool \c pool. The created tasklet calls * \c task_func() with \c arg when it is scheduled. * - * If \c newtask is \c NULL, this routine creates an unnamed tasklet. The + * If \c newtask is \c NULL, this routine creates an unnamed tasklet. An * unnamed tasklet is automatically released on the completion of * \c task_func(). Otherwise, \c newtask must be explicitly freed by * \c ABT_thread_free(). @@ -85,7 +85,7 @@ int ABT_task_create(ABT_pool pool, void (*task_func)(void *), void *arg, * tasklet to the pool \c pool. The created tasklet calls \c task_func() with * \c arg when it is scheduled. * - * If \c newtask is \c NULL, this routine creates an unnamed tasklet. The + * If \c newtask is \c NULL, this routine creates an unnamed tasklet. An * unnamed tasklet is automatically released on the completion of * \c task_func(). Otherwise, \c newtask must be explicitly freed by * \c ABT_thread_free(). @@ -147,6 +147,9 @@ int ABT_task_create_on_xstream(ABT_xstream xstream, void (*task_func)(void *), * The functionality of this routine is the same as \c ABT_thread_revive() * except for the error code. \c ABT_task_revive() returns \c ABT_ERR_INV_TASK * in a case where \c ABT_thread_revive() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_revive()} */ int ABT_task_revive(ABT_pool pool, void (*task_func)(void *), void *arg, ABT_task *task) @@ -165,6 +168,9 @@ int ABT_task_revive(ABT_pool pool, void (*task_func)(void *), void *arg, * \c ABT_task_free() sets \c task to \c ABT_TASK_NULL instead of * \c ABT_THREAD_NULL. \c ABT_task_free() returns \c ABT_ERR_INV_TASK in a case * where \c ABT_thread_free() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_free()} */ int ABT_task_free(ABT_task *task) { @@ -183,6 +189,9 @@ int ABT_task_free(ABT_task *task) * The functionality of this routine is the same as \c ABT_thread_join() except * for the error code. \c ABT_task_join() returns \c ABT_ERR_INV_TASK in a case * where \c ABT_thread_join() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_join()} */ int ABT_task_join(ABT_task task) { @@ -198,6 +207,9 @@ int ABT_task_join(ABT_task task) * The functionality of this routine is the same as \c ABT_thread_cancel() * except for the error code. \c ABT_task_cancel() returns \c ABT_ERR_INV_TASK * in a case where \c ABT_thread_cancel() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_cancel()} */ int ABT_task_cancel(ABT_task task) { @@ -214,7 +226,7 @@ int ABT_task_cancel(ABT_task task) * \c task. * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_get_thread()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_get_thread()} * * @changev20 * \DOC_DESC_V1X_NOYIELDABLE{\c ABT_ERR_INV_TASK} @@ -265,7 +277,7 @@ int ABT_task_self(ABT_task *task) * \c ABT_task_self_id() returns the ID of the calling work unit through \c id. * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_get_thread_id()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_get_thread_id()} * * @changev20 * \DOC_DESC_V1X_NOYIELDABLE{\c ABT_ERR_INV_TASK} @@ -314,6 +326,9 @@ int ABT_task_self_id(ABT_unit_id *id) * \c ABT_thread_get_last_xstream() except for the error code. * \c ABT_task_get_xstream() returns \c ABT_ERR_INV_TASK in a case where * \c ABT_thread_get_last_xstream() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_get_last_xstream()} */ int ABT_task_get_xstream(ABT_task task, ABT_xstream *xstream) { @@ -324,32 +339,30 @@ int ABT_task_get_xstream(ABT_task task, ABT_xstream *xstream) /** * @ingroup TASK - * @brief Get a state of a work unit. + * @brief Get a state of a tasklet. * - * \c ABT_task_get_state() returns the state of the work unit \c task through + * \c ABT_task_get_state() returns the state of the tasklet \c task through * \c state. * * \DOC_DESC_ATOMICITY_WORK_UNIT_STATE * - * @changev20 - * \DOC_DESC_V1X_TASK_STATE_ACCEPT_THREAD{\c task, \c ABT_ERR_INV_TASK} - * @endchangev20 + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_get_state()} * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH * * @errors * \DOC_ERROR_SUCCESS - * \DOC_ERROR_INV_THREAD_HANDLE{\c thread} * \DOC_ERROR_INV_TASK_HANDLE{\c thread} - * \DOC_V1X \DOC_ERROR_INV_TASK_Y{\c thread} + * \DOC_ERROR_INV_TASK_Y{\c thread} * * @undefined * \DOC_UNDEFINED_UNINIT * \DOC_UNDEFINED_NULL_PTR{\c state} * - * @param[in] task work unit handle - * @param[out] state state of \c work unit + * @param[in] task tasklet handle + * @param[out] state state of \c task * @return Error code */ int ABT_task_get_state(ABT_task task, ABT_task_state *state) @@ -375,6 +388,9 @@ int ABT_task_get_state(ABT_task task, ABT_task_state *state) * \c ABT_thread_get_last_pool() except for the error code. * \c ABT_task_get_last_pool() returns \c ABT_ERR_INV_TASK in a case where * \c ABT_thread_get_last_pool() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_get_last_pool()} */ int ABT_task_get_last_pool(ABT_task task, ABT_pool *pool) { @@ -391,6 +407,9 @@ int ABT_task_get_last_pool(ABT_task task, ABT_pool *pool) * \c ABT_thread_get_last_pool_id() except for the error code. * \c ABT_task_get_last_pool_id() returns \c ABT_ERR_INV_TASK in a case where * \c ABT_thread_get_last_pool_id() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_get_last_pool_id()} */ int ABT_task_get_last_pool_id(ABT_task task, int *id) { @@ -407,6 +426,9 @@ int ABT_task_get_last_pool_id(ABT_task task, int *id) * \c ABT_thread_set_migratable() except for the error code. * \c ABT_task_set_migratable() returns \c ABT_ERR_INV_TASK in a case where * \c ABT_thread_set_migratable() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_set_migratable()} */ int ABT_task_set_migratable(ABT_task task, ABT_bool flag) { @@ -423,6 +445,9 @@ int ABT_task_set_migratable(ABT_task task, ABT_bool flag) * \c ABT_thread_is_migratable() except for the error code. * \c ABT_task_is_migratable() returns \c ABT_ERR_INV_TASK in a case where * \c ABT_thread_is_migratable() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_is_migratable()} */ int ABT_task_is_migratable(ABT_task task, ABT_bool *flag) { @@ -437,13 +462,16 @@ int ABT_task_is_migratable(ABT_task task, ABT_bool *flag) * @brief Check if a work unit is unnamed * * The functionality of this routine is the same as \c ABT_thread_is_unnamed(). + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_is_unnamed()} */ int ABT_task_is_unnamed(ABT_task task, ABT_bool *flag); #endif /** * @ingroup TASK - * @brief Compare two tasklet handles for equality. + * @brief Compare two work-unit handles for equality. * * The functionality of this routine is the same as \c ABT_thread_equal(). */ @@ -459,6 +487,9 @@ int ABT_task_equal(ABT_task task1, ABT_task task2, ABT_bool *result) * The functionality of this routine is the same as \c ABT_thread_get_id() * except for the error code. \c ABT_task_get_id() returns \c ABT_ERR_INV_TASK * in a case where \c ABT_thread_get_id() returns \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_get_id()} */ int ABT_task_get_id(ABT_task task, ABT_unit_id *task_id) { @@ -469,12 +500,15 @@ int ABT_task_get_id(ABT_task task, ABT_unit_id *task_id) /** * @ingroup TASK - * @brief Retrieve an argument for a work unit function of a work unit. + * @brief Retrieve an argument for a work-unit function of a work unit. * * The functionality of this routine is the same as \c ABT_thread_get_arg() * except for the error code. \c ABT_task_get_arg() returns * \c ABT_ERR_INV_TASK in a case where \c ABT_thread_get_arg() returns * \c ABT_ERR_INV_THREAD. + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_get_arg()} */ int ABT_task_get_arg(ABT_task task, void **arg) { @@ -490,6 +524,9 @@ int ABT_task_get_arg(ABT_task task, void **arg) * * The functionality of this routine is the same as * \c ABT_thread_set_specific(). + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_set_specific()} */ int ABT_task_set_specific(ABT_task task, ABT_key key, void *value); #endif @@ -501,6 +538,9 @@ int ABT_task_set_specific(ABT_task task, ABT_key key, void *value); * * The functionality of this routine is the same as * \c ABT_thread_get_specific(). + * + * @note + * \DOC_NOTE_REPLACEMENT{\c ABT_thread_get_specific()} */ int ABT_task_get_specific(ABT_task task, ABT_key key, void **value); #endif diff --git a/src/thread.c b/src/thread.c index ec1f6cbab..bbcf0253b 100644 --- a/src/thread.c +++ b/src/thread.c @@ -34,6 +34,7 @@ static ABTI_key g_thread_mig_data_key = /** @defgroup ULT User-level Thread (ULT) * This group is for User-level Thread (ULT). + * A ULT is a work unit that can yield. */ /** @@ -42,8 +43,8 @@ static ABTI_key g_thread_mig_data_key = * * \c ABT_thread_create() creates a new ULT, given by the attributes \c attr, * associates it with the pool \c pool, and returns its handle through - * \c newthread. This routine pushes the created ULT to the pool \c pool. The - * created ULT calls \c thread_func() with \c arg when it is scheduled. + * \c newthread. This routine pushes the created ULT to \c pool. The created + * ULT calls \c thread_func() with \c arg when it is scheduled. * * \c attr can be created by \c ABT_thread_attr_create(). If the user passes * \c ABT_THREAD_ATTR_NULL for \c attr, the default ULT attribute is used. @@ -54,7 +55,7 @@ static ABTI_key g_thread_mig_data_key = * This routine copies \c attr, so the user can free \c attr after this routine * returns. * - * If \c newthread is \c NULL, this routine creates an unnamed ULT. The unnamed + * If \c newthread is \c NULL, this routine creates an unnamed ULT. An unnamed * ULT is automatically released on the completion of \c thread_func(). * Otherwise, \c newthread must be explicitly freed by \c ABT_thread_free(). * @@ -133,7 +134,7 @@ int ABT_thread_create(ABT_pool pool, void (*thread_func)(void *), void *arg, * This routine copies \c attr, so the user can free \c attr after this routine * returns. * - * If \c newthread is \c NULL, this routine creates an unnamed ULT. The unnamed + * If \c newthread is \c NULL, this routine creates an unnamed ULT. An unnamed * ULT is automatically released on the completion of \c thread_func(). * Otherwise, \c newthread must be explicitly freed by \c ABT_thread_free(). * @@ -202,7 +203,7 @@ int ABT_thread_create_on_xstream(ABT_xstream xstream, * @brief Create a set of new ULTs. * * \c ABT_thread_create_many() creates a set of new ULTs, i.e., \c num_threads - * ULTs, having the same ULT attribute \c attr and returns ULT handles to + * ULTs, having the same ULT attribute \c attr and returns ULT handles through * \c newthread_list. Each newly created ULT calls the corresponding function * of \c thread_func_list that has \c num_threads ULT functions with the * corresponding argument of \c arg_list that has \c num_threads argument @@ -220,13 +221,13 @@ int ABT_thread_create_on_xstream(ABT_xstream xstream, * Since this routine uses the same ULT attribute for creating all ULTs, this * routine does not support a user-provided stack. * - * If \c newthread_list is \c NULL, this routine creates unnamed ULTs. The + * If \c newthread_list is \c NULL, this routine creates unnamed ULTs. An * unnamed ULT is automatically released on the completion of \c thread_func(). * Otherwise, the creates ULTs must be explicitly freed by \c ABT_thread_free(). * * This routine is deprecated because this routine does not provide a way for * the user to keep track of an error that happens during this routine. The - * user should use \c ABT_thread_create() instead. + * user should call \c ABT_thread_create() multiple times instead. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH @@ -305,11 +306,13 @@ int ABT_thread_create_many(int num_threads, ABT_pool *pool_list, * @ingroup ULT * @brief Revive a terminated work unit. * - * \c ABT_thread_revive() revives the work unit \c thread with \c thread_func - * and \c arg. This routine does not change the attributes of \c thread. The - * revived work unit is pushed to \c pool. Although this routine takes a - * pointer of \c ABT_thread, the handle of \c thread is not updated by this - * routine. + * \c ABT_thread_revive() revives the work unit \c thread with the new work-unit + * function \c thread_func() and its argument \c arg. This routine does not + * change the attributes of \c thread. The revived work unit is pushed to the + * pool \c pool. + * + * Although this routine takes a pointer of \c ABT_thread, the handle of + * \c thread is not updated by this routine. * * \c thread must be a terminated work unit that has not been freed. A work * unit that is blocked on by another caller may not be revived. @@ -371,9 +374,8 @@ int ABT_thread_revive(ABT_pool pool, void (*thread_func)(void *), void *arg, * @ingroup ULT * @brief Free a work unit. * - * \c ABT_thread_free() deallocates the resource used for the thread \c thread. - * If \c thread is a ULT, \c thread is set to \c ABT_THREAD_NULL. If \c thread - * is a tasklet, \c thread is set to \c ABT_TASK_NULL. If \c thread is still + * \c ABT_thread_free() deallocates the resource used for the work unit + * \c thread and sets \c thread to \c ABT_THREAD_NULL. If \c thread is still * running, this routine will be blocked on \c thread until \c thread * terminates. * @@ -381,7 +383,7 @@ int ABT_thread_revive(ABT_pool pool, void (*thread_func)(void *), void *arg, * Because an unnamed work unit will be freed immediately after its termination, * an unnamed work unit cannot be freed by this routine.\n * This routine cannot free the calling work unit.\n - * This routine cannot free the main ULT or the main scheduler ULT.\n + * This routine cannot free the main ULT or the main scheduler's ULT.\n * Only one caller can join or free the same work unit. * * @changev11 @@ -401,7 +403,7 @@ int ABT_thread_revive(ABT_pool pool, void (*thread_func)(void *), void *arg, * @undefined * \DOC_UNDEFINED_UNINIT * \DOC_UNDEFINED_NULL_PTR{\c thread} - * \DOC_UNDEFINED_WORK_UNIT_BLOCKED{\c thread, \c ABT_thread_join() and + * \DOC_UNDEFINED_WORK_UNIT_BLOCKED{\c thread, \c ABT_thread_join() or * \c ABT_thread_free()} * \DOC_UNDEFINED_THREAD_UNSAFE_FREE{\c thread} * @@ -440,12 +442,14 @@ int ABT_thread_free(ABT_thread *thread) * @brief Free a set of work units. * * \c ABT_thread_free_many() deallocates a set of work units listed in - * \c thread_list that has \c num_threads work unit handles. Each handle - * referenced by \c thread_list is set to \c ABT_THRAED_NULL. + * \c thread_list that has \c num_threads work unit handles. If any of work + * units is still running, this routine will be blocked on the running work unit + * until it terminates. Each handle referenced by \c thread_list is set to + * \c ABT_THRAED_NULL. * * This routine is deprecated because this routine does not provide a way for * the user to keep track of an error that happens during this routine. The - * user should use \c ABT_thread_free() instead. + * user should call \c ABT_thread_free() multiple times instead. * * \DOC_DESC_ATOMICITY_WORK_UNIT_STATE * @@ -514,7 +518,7 @@ int ABT_thread_free_many(int num_threads, ABT_thread *thread_list) * * @undefined * \DOC_UNDEFINED_UNINIT - * \DOC_UNDEFINED_WORK_UNIT_BLOCKED{\c thread, \c ABT_thread_join() and + * \DOC_UNDEFINED_WORK_UNIT_BLOCKED{\c thread, \c ABT_thread_join() or * \c ABT_thread_free()} * \DOC_UNDEFINED_THREAD_UNSAFE{\c thread} * @@ -547,7 +551,7 @@ int ABT_thread_join(ABT_thread thread) * * This routine is deprecated because this routine does not provide a way for * the user to keep track of an error that happens during this routine. The - * user should use \c ABT_thread_join() instead. + * user should call \c ABT_thread_join() multiple times instead. * * \DOC_DESC_ATOMICITY_WORK_UNIT_STATE * @@ -587,7 +591,7 @@ int ABT_thread_join_many(int num_threads, ABT_thread *thread_list) * return if it succeeds. * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_exit()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_exit()} * * @changev20 * \DOC_DESC_V1X_RETURN_UNINITIALIZED @@ -599,7 +603,7 @@ int ABT_thread_join_many(int num_threads, ABT_thread *thread_list) * @errors * \DOC_ERROR_INV_XSTREAM_EXT * \DOC_ERROR_INV_THREAD_NY - * \DOC_ERROR_INV_THREAD_PRIMARY_ULT{\c the caller} + * \DOC_ERROR_INV_THREAD_PRIMARY_ULT{the caller} * \DOC_V1X \DOC_ERROR_UNINITIALIZED * * @undefined @@ -624,7 +628,7 @@ int ABT_thread_exit(void) /** * @ingroup ULT - * @brief Send a termination request to a work unit. + * @brief Send a cancellation request to a work unit. * * \c ABT_thread_cancel() sends a cancellation request to the work unit * \c thread. \c thread may terminate before its thread function completes. @@ -644,7 +648,7 @@ int ABT_thread_exit(void) * @errors * \DOC_ERROR_SUCCESS * \DOC_ERROR_INV_THREAD_HANDLE{\c thread} - * \DOC_ERROR_INV_THREAD_PRIMARY_ULT{\c the caller} + * \DOC_ERROR_INV_THREAD_PRIMARY_ULT{the caller} * \DOC_ERROR_FEATURE_NA{the cancellation feature} * * @undefined @@ -678,7 +682,7 @@ int ABT_thread_cancel(ABT_thread thread) * \c thread. * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_get_thread()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_get_thread()} * * @changev20 * \DOC_DESC_V1X_NOTASK{\c ABT_ERR_INV_THREAD} @@ -729,7 +733,7 @@ int ABT_thread_self(ABT_thread *thread) * \c id. * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_get_thread_id()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_get_thread_id()} * * @changev20 * \DOC_DESC_V1X_NOTASK{\c ABT_ERR_INV_THREAD} @@ -970,7 +974,7 @@ int ABT_thread_set_associated_pool(ABT_thread thread, ABT_pool pool) /** * @ingroup ULT - * @brief Yield the calling ULT to the specific ULT. + * @brief Yield the calling ULT to another ULT. * * \c ABT_thread_yield_to() yields the calling ULT and schedules the ULT * \c thread that is in its associated pool. The calling ULT will be pushed to @@ -1104,7 +1108,7 @@ int ABT_thread_yield_to(ABT_thread thread) * its associated pool. Its parent ULT will be resumed. * * @note - * \DOC_DESC_REPLACEMENT{\c ABT_self_yield()} + * \DOC_NOTE_REPLACEMENT{\c ABT_self_yield()} * * @changev20 * \DOC_DESC_V1X_YIELD_TASK @@ -1155,8 +1159,8 @@ int ABT_thread_yield(void) * @brief Resume a ULT. * * \c ABT_thread_resume() resumes the ULT \c thread blocked by - * \c ABT_thread_suspend() schedulable by making \c thread ready and pushing - * \c thread to its associated pool. + * \c ABT_self_suspend() by making \c thread ready and pushing \c thread to + * its associated pool. * * @changev20 * \DOC_DESC_V1X_CRUDE_BLOCKED_CHECK{\c thread, \c ABT_ERR_THREAD} @@ -1206,8 +1210,8 @@ int ABT_thread_resume(ABT_thread thread) * \c ABT_thread_migrate_to_xstream() requests a migration of the work unit * \c thread to any pool associated with the main scheduler of execution stream * \c xstream. The previous migration request is overwritten by the new - * migration request. The requested work unit may be migrated before its work - * unit function completes. + * migration request. The requested work unit may be migrated before its + * work-unit function completes. * * @note * \DOC_NOTE_TIMING_REQUEST @@ -1215,8 +1219,8 @@ int ABT_thread_resume(ABT_thread thread) * \DOC_DESC_ATOMICITY_WORK_UNIT_REQUEST * * It is the user's responsibility to keep \c xstream, its main scheduler, and - * its associated pools until the migration process completes or \c thread is - * freed, whichever is earlier. + * its associated pools alive until the migration process completes or \c thread + * is freed, whichever is earlier. * * @changev11 * \DOC_DESC_V10_ACCEPT_TASK{\c thread} @@ -1296,7 +1300,7 @@ int ABT_thread_migrate_to_xstream(ABT_thread thread, ABT_xstream xstream) * \c ABT_thread_migrate_to_sched() requests a migration of the work unit * \c thread to any pool associated with the scheduler \c sched. The previous * migration request is overwritten by the new migration request. The requested - * work unit may be migrated before its work unit function completes. + * work unit may be migrated before its work-unit function completes. * * @note * \DOC_NOTE_TIMING_REQUEST @@ -1304,8 +1308,8 @@ int ABT_thread_migrate_to_xstream(ABT_thread thread, ABT_xstream xstream) * \DOC_DESC_ATOMICITY_WORK_UNIT_REQUEST * * It is the user's responsibility to keep \c sched and its associated pools - * until the migration process completes or \c thread is freed, whichever is - * earlier. + * alive until the migration process completes or \c thread is freed, whichever + * is earlier. * * @changev11 * \DOC_DESC_V10_ACCEPT_TASK{\c thread} @@ -1381,15 +1385,15 @@ int ABT_thread_migrate_to_sched(ABT_thread thread, ABT_sched sched) * \c ABT_thread_migrate_to_pool() requests a migration of the work unit * \c thread to the pool \c pool. The previous migration request will be * overwritten by the new migration request. The requested work unit may be - * migrated before its work unit function completes. + * migrated before its work-unit function completes. * * @note * \DOC_NOTE_TIMING_REQUEST * * \DOC_DESC_ATOMICITY_WORK_UNIT_REQUEST * - * It is the user's responsibility to keep \c pool until the migration process - * completes or \c thread is freed, whichever is earlier. + * It is the user's responsibility to keep \c pool alive until the migration + * process completes or \c thread is freed, whichever is earlier. * * @changev11 * \DOC_DESC_V10_ACCEPT_TASK{\c thread} @@ -1447,13 +1451,13 @@ int ABT_thread_migrate_to_pool(ABT_thread thread, ABT_pool pool) /** * @ingroup ULT * @brief Request a migration of a work unit to any available execution - * streams. + * stream. * * \c ABT_thread_migrate() requests a migration of the work unit \c thread to * one of the execution streams. The last execution stream of \c thread is not * chosen as the target execution stream. The previous migration request will * be overwritten by the new migration request. The requested work unit may be - * migrated before its work unit function completes. + * migrated before its work-unit function completes. * * @note * \DOC_NOTE_TIMING_REQUEST @@ -1461,12 +1465,11 @@ int ABT_thread_migrate_to_pool(ABT_thread thread, ABT_pool pool) * \DOC_DESC_ATOMICITY_WORK_UNIT_REQUEST * * It is the user's responsibility to keep all the execution streams, the main - * schedulers, and their associated pools until the migration process completes - * or \c thread is freed, whichever is earlier. + * schedulers, and their associated pools alive until the migration process + * completes or \c thread is freed, whichever is earlier. * - * This routine is deprecated because this routine will not choose an execution - * stream that is expected by the user while this routine is significantly - * restrictive. The user should use other migration functions instead. + * This routine is deprecated because this routine is significantly restrictive. + * The user should use other migration functions instead. * * @changev11 * \DOC_DESC_V10_ACCEPT_TASK{\c thread} @@ -1512,7 +1515,7 @@ int ABT_thread_migrate(ABT_thread thread) ABTI_CHECK_TRUE(!(p_thread->type & ABTI_THREAD_TYPE_MAIN_SCHED), ABT_ERR_INV_THREAD); - /* Copy the target executions streams. */ + /* Copy the target execution streams. */ int i, num_xstreams, abt_errno; ABTI_xstream **xstreams; ABTI_spinlock_acquire(&p_global->xstream_list_lock); @@ -1575,20 +1578,16 @@ int ABT_thread_migrate(ABT_thread thread) /** * @ingroup ULT - * @brief Set a callback function in a work unit. + * @brief Register a callback function in a work unit. * - * \c ABT_thread_set_callback() sets the callback function \c cb_func() and its - * argument \c cb_arg in the work unit \c thread. If \c cb_func is not \c NULL, - * \c cb_func() is called with \c cb_arg as an argument on the migration of - * \c thread. If \c cb_func is \c NULL, \c thread not call a callback function - * on its migration. - * - * If the callback function is set, a callback function \c cb_func() will be - * called every time on migration of the associated work unit. The first - * argument of \c cb_arg() is the handle of a migrated work unit. The second + * \c ABT_thread_set_callback() registers the callback function \c cb_func() and + * its argument \c cb_arg in the work unit \c thread. If \c cb_func is not + * \c NULL, \c cb_func() is called when \c thread is migrated. The first + * argument of \c cb_func() is the handle of a migrated work unit. The second * argument is \c cb_arg passed to this routine. The caller of the callback * function is undefined, so a program that relies on the caller is - * non-conforming. + * non-conforming. If \c cb_func is \c NULL, this routine unregisters a + * callback function in \c thread. * * @changev11 * \DOC_DESC_V10_ACCEPT_TASK{\c thread} @@ -1789,12 +1788,13 @@ int ABT_thread_is_primary(ABT_thread thread, ABT_bool *is_primary) * @brief Check if a work unit is unnamed * * \c ABT_thread_is_primary() checks if the work unit \c thread is unnamed and - * returns the result through \c flag. If \c thread is unnamed, \c flag is set - * to \c ABT_TRUE. Otherwise, \c flag is set to \c ABT_FALSE. + * returns the result through \c is_unnamed. If \c thread is unnamed, + * \c is_unnamed is set to \c ABT_TRUE. Otherwise, \c is_unnamed is set to + * \c ABT_FALSE. * * @note * A handle of an unnamed work unit can be obtained by, for example, running - * \c ABT_thread_self() on an unnamed work unit. + * \c ABT_self_get_thread() on an unnamed work unit. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH @@ -1805,7 +1805,7 @@ int ABT_thread_is_primary(ABT_thread thread, ABT_bool *is_primary) * * @undefined * \DOC_UNDEFINED_UNINIT - * \DOC_UNDEFINED_NULL_PTR{\c flag} + * \DOC_UNDEFINED_NULL_PTR{\c is_unnamed} * * @param[in] thread work unit handle * @param[out] is_unnamed result (\c ABT_TRUE: unnamed, \c ABT_FALSE: not) @@ -1872,7 +1872,7 @@ int ABT_thread_equal(ABT_thread thread1, ABT_thread thread2, ABT_bool *result) * * \c ABT_thread_get_stacksize() returns the stack size of the work unit * \c thread in bytes through \c stacksize. If \c thread does not have a stack - * managed by the Argobots runtime (e.g., the tasklet or the primary ULT), + * managed by the Argobots runtime (e.g., a tasklet or the primary ULT), * \c stacksize is set to 0. * * @changev11 @@ -1911,7 +1911,7 @@ int ABT_thread_get_stacksize(ABT_thread thread, size_t *stacksize) * @ingroup ULT * @brief Get ID of a work unit * - * \c ABT_thread_get_id() returns the ID of the work unit \c a thread through + * \c ABT_thread_get_id() returns the ID of the work unit \c thread through * \c thread_id. * * @changev11 @@ -1944,9 +1944,9 @@ int ABT_thread_get_id(ABT_thread thread, ABT_unit_id *thread_id) /** * @ingroup ULT - * @brief Set an argument for a work unit function of a work unit. + * @brief Set an argument for a work-unit function of a work unit. * - * \c ABT_thread_set_arg() sets the argument \c arg for the work unit function + * \c ABT_thread_set_arg() sets the argument \c arg for the work-unit function * of the work unit \c thread. * * @changev11 @@ -1965,7 +1965,7 @@ int ABT_thread_get_id(ABT_thread thread, ABT_unit_id *thread_id) * \DOC_UNDEFINED_THREAD_UNSAFE{\c thread} * * @param[in] thread work unit handle - * @param[in] arg argument for the work unit function + * @param[in] arg argument for the work-unit function * @return Error code */ int ABT_thread_set_arg(ABT_thread thread, void *arg) @@ -1979,9 +1979,9 @@ int ABT_thread_set_arg(ABT_thread thread, void *arg) /** * @ingroup ULT - * @brief Retrieve an argument for a work unit function of a work unit. + * @brief Retrieve an argument for a work-unit function of a work unit. * - * \c ABT_thread_get_arg() returns the argument for the work unit function of + * \c ABT_thread_get_arg() returns the argument for the work-unit function of * the work unit \c thread through \c arg. * * @changev11 @@ -2000,7 +2000,7 @@ int ABT_thread_set_arg(ABT_thread thread, void *arg) * \DOC_UNDEFINED_NULL_PTR{\c arg} * * @param[in] thread work unit handle - * @param[out] arg argument for the work unit function + * @param[out] arg argument for the work-unit function * @return Error code */ int ABT_thread_get_arg(ABT_thread thread, void **arg) @@ -2014,9 +2014,9 @@ int ABT_thread_get_arg(ABT_thread thread, void **arg) /** * @ingroup ULT - * @brief Set a value with a work-unit-specific key in a work unit. + * @brief Set a value with a work-unit-specific data key in a work unit. * - * \c ABT_thread_set_specific() associates the value \c value of the + * \c ABT_thread_set_specific() associates the value \c value with the * work-unit-specific data key \c key in the work unit \c thread. * * \DOC_DESC_ATOMICITY_WORK_UNIT_KEY @@ -2060,11 +2060,13 @@ int ABT_thread_set_specific(ABT_thread thread, ABT_key key, void *value) /** * @ingroup ULT - * @brief Get a value associated with a work-unit-specific key in a work unit. + * @brief Get a value associated with a work-unit-specific data key in a work + * unit. * - * \c ABT_thread_get_specific() returns the value of the work-unit-specific data - * key \c key in the work unit \c thread through \c value. If \c thread has - * never set a value for \c key, this routine sets \c value to \c NULL. + * \c ABT_thread_get_specific() returns the value associated with the + * work-unit-specific data key \c key in the work unit \c thread through + * \c value. If \c thread has never set a value for \c key, this routine sets + * \c value to \c NULL. * * \DOC_DESC_ATOMICITY_WORK_UNIT_KEY * @@ -2113,7 +2115,8 @@ int ABT_thread_get_specific(ABT_thread thread, ABT_key key, void **value) * @endchangev20 * * @contexts - * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH + * \DOC_V1X \DOC_CONTEXT_INIT_NOTASK \DOC_CONTEXT_NOCTXSWITCH + * \DOC_V20 \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH * * @errors * \DOC_ERROR_SUCCESS diff --git a/src/thread_attr.c b/src/thread_attr.c index 8bee68768..e432d051b 100644 --- a/src/thread_attr.c +++ b/src/thread_attr.c @@ -18,11 +18,11 @@ static void thread_attr_set_stack(ABTI_global *p_global, * @ingroup ULT_ATTR * @brief Create a new ULT attribute. * - * \c ABT_thread_attr_create() creates a ULT attribute with default attribute - * values and returns its handle through \c newattr. + * \c ABT_thread_attr_create() creates a ULT attribute with the default + * attribute parameters and returns its handle through \c newattr. * * The default parameters are as follows: - * - Using a memory pool for stack allocation. + * - Using a memory pool for stack allocation if a memory pool is enabled. * - Default stack size, which can be set via \c ABT_THREAD_STACKSIZE. * - Migratable. * - Invoking no callback function on migration. @@ -169,8 +169,8 @@ int ABT_thread_attr_set_stack(ABT_thread_attr attr, void *stackaddr, * @brief Get stack attributes from a ULT attribute. * * \c ABT_thread_attr_get_stack() retrieves the stack address and the stack size - * (in bytes) from the ULT attribute \c attr to \c stackaddr and \c stacksize, - * respectively. + * (in bytes) from the ULT attribute \c attr and returns values through + * \c stackaddr and \c stacksize, respectively. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH @@ -204,10 +204,10 @@ int ABT_thread_attr_get_stack(ABT_thread_attr attr, void **stackaddr, * @ingroup ULT_ATTR * @brief Set stack size in a ULT attribute. * - * \c ABT_thread_attr_set_stacksize() sets the stack size \c stacksize - * (in bytes) in the ULT attribute \c attr. If the stack memory has been - * already set by \c ABT_thread_attr_set_stack(), this routine updates the stack - * size while keeping the stack memory in \c attr. + * \c ABT_thread_attr_set_stacksize() sets the stack size \c stacksize (in + * bytes) in the ULT attribute \c attr. If the stack memory has already been + * set by \c ABT_thread_attr_set_stack(), this routine updates the stack size + * while keeping the stack memory in \c attr. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH @@ -240,8 +240,8 @@ int ABT_thread_attr_set_stacksize(ABT_thread_attr attr, size_t stacksize) * @ingroup ULT_ATTR * @brief Get the stack size from a ULT attribute. * - * \c ABT_thread_attr_get_stacksize() returns the stack size (in bytes) through - * \c stacksize from the ULT attribute \c attr. + * \c ABT_thread_attr_get_stacksize() retrieves the stack size (in bytes) from + * the ULT attribute \c attr and returns it through \c stacksize. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH @@ -276,12 +276,12 @@ int ABT_thread_attr_get_stacksize(ABT_thread_attr attr, size_t *stacksize) * \c NULL, this routine unsets the callback function in \c attr. Otherwise, * \c cb_func and \c cb_arg are set in \c attr. * - * If the callback function is set, a callback function \c cb_func() will be - * called every time on the migration of the associated work unit. The first - * argument of \c cb_arg() is the handle of a migrated work unit. The second + * If the callback function is registered to a work unit, \c cb_func() will be + * called every time when the corresponding work unit is migrated. The first + * argument of \c cb_func() is the handle of a migrated work unit. The second * argument is \c cb_arg passed to this routine. The caller of the callback - * function is undefined, so a program that relies on the caller is - * non-conforming. + * function is undefined, so a program that relies on the caller of \c cb_func() + * is non-conforming. * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH diff --git a/src/timer.c b/src/timer.c index e3e91ad4c..a1843c308 100644 --- a/src/timer.c +++ b/src/timer.c @@ -74,9 +74,9 @@ int ABT_timer_create(ABT_timer *newtimer) * @ingroup TIMER * @brief Duplicate a timer. * - * \c ABT_timer_dup() creates a new timer and copies the time values from the - * timer \c timer to the new timer. The handle of the new timer is returned - * through \c newtimer. + * \c ABT_timer_dup() creates a new timer and copies the start and stop time + * of the timer \c timer to the new timer. The handle of the new timer is + * returned through \c newtimer. * * The created timer must be freed by \c ABT_timer_free() after its use. * @@ -215,8 +215,8 @@ int ABT_timer_stop(ABT_timer timer) * * \c ABT_timer_read() returns the time difference in seconds between the start * time and the stop time of the timer \c timer through \c secs. If either the - * start time or the stop time \c timer has not been set, \c secs is set to an - * undefined value. + * start time or the stop time of \c timer has not been set, \c secs is set to + * an undefined value. * * \DOC_DESC_TIMER_RESOLUTION * diff --git a/src/tool.c b/src/tool.c index 053a8290d..5e03ff766 100644 --- a/src/tool.c +++ b/src/tool.c @@ -17,36 +17,36 @@ ABTU_ret_err static inline int tool_query(ABTI_tool_context *p_tctx, /** * @ingroup TOOL - * @brief Register a callback function for work unit events. + * @brief Register a callback function for work-unit events. * - * \c ABT_tool_register_thread_callback() sets the callback function - * \c cb_func() for work unit events. The events are enabled if - * \c event_mask have their corresponding bits. The other events are disabled. - * Users can stop the event callback by setting \c cb_func to \c NULL. + * \c ABT_tool_register_thread_callback() registers the callback function + * \c cb_func() for work-unit events. The events are enabled if \c event_mask + * have the corresponding bits. The other events are disabled. The routine + * unregisters the callback function if \c cb_func is \c NULL. * * \c 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 second argument: an underlying execution stream * - The third argument: an event code (see \c ABT_TOOL_EVENT_THREAD) * - The fourth argument: a tool context for \c ABT_tool_query_thread() - * - The fifth argument: \c user_arg passed to this routine. + * - The fifth argument: \c user_arg passed to this routine * - * If the event occurs on an external thread, \c ABT_XSTREAM_NULL is passed as - * the second argument. The returned tool context is valid only before the - * callback function finishes. + * If an event occurs on an external thread, \c ABT_XSTREAM_NULL is passed as + * the second argument. The returned tool context is valid only in the callback + * function. * * 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 \c ABT_thread_get_state()) in \c cb_func(). + * in an intermediate state, so the user should not read any internal state of + * such an object (e.g., by \c ABT_thread_get_state()) in \c cb_func(). * Instead, the user should use \c ABT_tool_query_thread(). The caller of * \c 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 \c cb_func() is non-conforming. * - * This routine can be called while other work unit events are happening. This - * routine atomically sets \c cb_func(), \c event_mask, and \c user_arg at the - * same time. + * This routine can be called while other work-unit events are being triggered. + * This routine atomically registers \c cb_func(), \c event_mask, and + * \c user_arg at the same time. * * @note * Invoking an event in \c cb_func() may cause an infinite invocation of @@ -57,10 +57,10 @@ ABTU_ret_err static inline int tool_query(ABTI_tool_context *p_tctx, * * @note * Even after \c ABT_tool_register_thread_callback() returns, another event call - * might be still in the previous \c cb_func() and using the previous - * \c user_arg. Argobots does not provide a method to guarantee that the - * previous \c cb_func and \c user_arg get unused. Hence, the user needs to - * carefully maintain consistency before and after + * might not have finished. If so, the previous \c cb_func() might be using the + * previous \c user_arg. Argobots does not provide a method to guarantee that + * the previous \c cb_func() and \c user_arg get unused. Hence, the user needs + * to carefully maintain consistency before and after * \c ABT_tool_register_thread_callback(). * * @contexts @@ -101,51 +101,61 @@ int ABT_tool_register_thread_callback(ABT_tool_thread_callback_fn cb_func, /** * @ingroup TOOL - * @brief Query information associated with a work unit event. + * @brief Query information associated with a work-unit event. * * \c ABT_tool_query_thread() returns information associated with the tool * context \c context through \c val. Because \c context is valid only in the * callback function, this function must be called in the callback function. * - * When \c query_kind is \c ABT_TOOL_QUERY_KIND_POOL, this routine sets \c val - * to \c ABT_pool of a pool to which a work unit is or will be pushed. The - * query is valid when \c event is \c THREAD_CREATE, \c THREAD_REVIVE, - * \c THREAD_YIELD, \c THREAD_RESUME. - * - * When \c query_kind is \c ABT_TOOL_QUERY_KIND_STACK_DEPTH, this routine sets - * \c val to the current depth of stackable work units as an \c 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 \a 1. The query is valid when \c event is \c THREAD_RUN (the depth - * after the work unit runs), \c THREAD_FINISH (the depth before the work unit - * finishes), \c THREAD_YIELD (the depth before the work unit yields), and + * When \c query_kind is \c ABT_TOOL_QUERY_KIND_POOL, \c val must be a pointer + * to a variable of type \c ABT_pool. This routine sets \c val to a handle of + * a pool to which a work unit is or will be pushed. This query is valid when + * \c event is \c THREAD_CREATE, \c THREAD_REVIVE, \c THREAD_YIELD, + * or \c THREAD_RESUME. + * + * When \c query_kind is \c ABT_TOOL_QUERY_KIND_STACK_DEPTH, \c val must be a + * pointer to a variable of type \c int. This routine sets \c val to the + * current depth of stacked work units while the level of the work unit + * associated with the main scheduler is zero. For example, if the current + * work unit is running directly on the main scheduler, the depth is \a 1. This + * query is valid when \c event is \c THREAD_RUN (the depth after the work unit + * runs), \c THREAD_FINISH (the depth before the work unit finishes), + * \c THREAD_YIELD (the depth before the work unit yields), or * \c THREAD_SUSPEND (the depth before the work unit suspends). * - * When \c query_kind is \c ABT_TOOL_QUERY_KIND_CALLER_TYPE, this routine sets - * \c val to \c ABT_exec_entity_type of an entity that incurs this event. The - * query is valid for all events. - * - * When \c query_kind is \c ABT_TOOL_QUERY_KIND_CALLER_HANDLE, this routine sets - * \c val to a handle of an entity that incurs this event. Specifically, this - * routine sets \c val to a work unit handle (\c ABT_thread) if the caller type - * is \c ABT_EXEC_ENTITY_TYPE_THREAD. If the caller is an external thread, this - * routine sets \c val to \c NULL. The query is valid for all events except for - * \c THREAD_CANCEL. Note that the caller is a previous work unit running on - * the same execution stream when \c event is \c THRAED_RUN. - * - * When \c query_kind is \c ABT_TOOL_QUERY_KIND_SYNC_OBJECT_TYPE, this routine - * sets \c val to \c ABT_sync_event_type of an synchronization object that - * incurs this event. The synchronization object is returned when \c query_kind - * is \c ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE. This query is valid for - * \c THREAD_YIELD and \c THREAD_SUSPEND. + * When \c query_kind is \c ABT_TOOL_QUERY_KIND_CALLER_TYPE, \c val must be a + * pointer to a variable of type \c ABT_exec_entity_type. This routine sets + * \c val to a type of an entity that incurs this event. This query is valid + * for all events. + * + * When \c query_kind is \c ABT_TOOL_QUERY_KIND_CALLER_HANDLE, \c val must be a + * pointer to a variable of a handle type of an entity that incurs this event. + * This routine sets \c val to a handle of an entity that incurs this event. + * Specifically, this routine sets \c val to a work unit handle (\c ABT_thread) + * if the caller type is \c ABT_EXEC_ENTITY_TYPE_THREAD. If the caller is an + * external thread, this routine sets \c val to \c NULL. The query is valid for + * all events except for \c THREAD_CANCEL. Note that the caller is the previous + * work unit running on the same execution stream when \c event is + * \c THRAED_RUN. + * + * When \c query_kind is \c ABT_TOOL_QUERY_KIND_SYNC_OBJECT_TYPE, \c val must be + * a pointer to a variable of type \c ABT_sync_event_type. This routine sets + * \c val to a type of the synchronization object that incurs this event. This + * query is valid when \c event is \c THREAD_YIELD or \c THREAD_SUSPEND. + * + * When \c query_kind is \c ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE, \c val must + * be a pointer to a variable of a handle type of the synchronization object + * that incurs this event. This routine sets \c val to a handle of the + * synchronization object that incurs this event. This query is valid when + * \c event is \c THREAD_YIELD or \c THREAD_SUSPEND. * * Synchronization events, \c ABT_sync_event_type, and synchronization objects * are mapped as follows: * * - \c ABT_SYNC_EVENT_TYPE_USER: * - * The user's explicit call (e.g., \c ABT_thread_yield()). The - * synchronization object is none, so \c NULL is set to \c val if + * A user's explicit call (e.g., \c ABT_thread_yield()). The synchronization + * object is none, so \c NULL is set to \c val if * \c ABT_TOOL_QUERY_KIND_SYNC_OBJECT_HANDLE is passed. * * - \c ABT_SYNC_EVENT_TYPE_XSTREAM_JOIN: @@ -192,18 +202,16 @@ int ABT_tool_register_thread_callback(ABT_tool_thread_callback_fn cb_func, * * - \c ABT_SYNC_EVENT_TYPE_OTHER: * - * Unclassified synchronization (e.g., \c ABT_xstream_exit()) The - * synchronization object is none, so \c NULL is set to \c val if + * Other synchronization (e.g., \c ABT_xstream_exit()). The synchronization + * object is none, so \c NULL is set to \c val if * \c 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 \c ABT_task_get_state()) in - * \c cb_func(). + * be in an intermediate state, so the user should not to read any internal + * state of such an object (e.g., by \c ABT_thread_get_state()) in \c cb_func(). * * @contexts - * \DOC_CONTEXT_TOOL_CALLBACK{the tool callback function} - * \DOC_CONTEXT_NOCTXSWITCH + * \DOC_CONTEXT_TOOL_CALLBACK \DOC_CONTEXT_NOCTXSWITCH * * @errors * \DOC_ERROR_SUCCESS diff --git a/src/unit.c b/src/unit.c index 5f675140b..19ca7b25a 100644 --- a/src/unit.c +++ b/src/unit.c @@ -14,9 +14,9 @@ * @brief Set the associated pool for a work unit. * * \c ABT_unit_set_associated_pool() changes the associated pool of the target - * work unit \c unit to \c pool. This routine must be called after \c unit is - * popped from its original associated pool (i.e., \c unit must not be inside - * any pool). + * work unit \c unit to the pool \c pool. This routine must be called + * after \c unit is popped from its original associated pool (i.e., \c unit must + * not be inside any pool). * * @contexts * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH