Skip to content

Commit

Permalink
Merge pull request #301 from shintaro-iwasaki/pr/self_wrapper
Browse files Browse the repository at this point in the history 
self: give new names to functions that target underlying ULTs or ESs
  • Loading branch information
@shintaro-iwasaki
shintaro-iwasaki authored Feb 9, 2021
2 parents e689eb5 + 8c5dd7c commit f816757
Show file tree
Hide file tree
Showing 15 changed files with 965 additions and 46 deletions.
2 changes: 2 additions & 0 deletions Doxyfile.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1870,6 +1870,8 @@ 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."
Expand Down
10 changes: 10 additions & 0 deletions src/include/abt.h.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1884,12 +1884,22 @@ int ABT_task_get_arg(ABT_task task, void **arg) ABT_API_PUBLIC;
#define ABT_task_get_specific ABT_thread_get_specific

/* Self */
int ABT_self_get_xstream(ABT_xstream *xstream) ABT_API_PUBLIC;
int ABT_self_get_xstream_rank(int *rank) ABT_API_PUBLIC;
int ABT_self_get_thread(ABT_thread *thread) ABT_API_PUBLIC;
int ABT_self_get_thread_id(ABT_unit_id *id) ABT_API_PUBLIC;
int ABT_self_set_specific(ABT_key key, void *value) ABT_API_PUBLIC;
int ABT_self_get_specific(ABT_key key, void **value) ABT_API_PUBLIC;
#define ABT_self_get_task ABT_self_get_thread
#define ABT_self_get_task_id ABT_self_get_thread_id
int ABT_self_get_type(ABT_unit_type *type) ABT_API_PUBLIC;
int ABT_self_is_primary(ABT_bool *is_primary) ABT_API_PUBLIC;
int ABT_self_on_primary_xstream(ABT_bool *on_primary) ABT_API_PUBLIC;
int ABT_self_is_unnamed(ABT_bool *is_unnamed) ABT_API_PUBLIC;
int ABT_self_get_last_pool_id(int *pool_id) ABT_API_PUBLIC;
int ABT_self_yield(void) ABT_API_PUBLIC;
int ABT_self_suspend(void) ABT_API_PUBLIC;
int ABT_self_exit(void) ABT_API_PUBLIC;
int ABT_self_set_arg(void *arg) ABT_API_PUBLIC;
int ABT_self_get_arg(void **arg) ABT_API_PUBLIC;

Expand Down
6 changes: 6 additions & 0 deletions src/key.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,9 @@ int ABT_key_free(ABT_key *key)
*
* \DOC_DESC_ATOMICITY_WORK_UNIT_KEY
*
* @note
* \DOC_DESC_REPLACEMENT{\c ABT_self_set_specific()}
*
* @changev20
* \DOC_DESC_V1X_RETURN_UNINITIALIZED
* @endchangev20
Expand Down Expand Up @@ -179,6 +182,9 @@ int ABT_key_set(ABT_key key, void *value)
*
* \DOC_DESC_ATOMICITY_WORK_UNIT_KEY
*
* @note
* \DOC_DESC_REPLACEMENT{\c ABT_self_get_specific()}
*
* @changev20
* \DOC_DESC_V1X_RETURN_UNINITIALIZED
* @endchangev20
Expand Down
293 changes: 293 additions & 0 deletions src/self.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,235 @@
* This group is for the self wok unit.
*/

/**
* @ingroup SELF
* @brief Get an execution stream that is running the calling work unit.
*
* \c ABT_self_get_xstream() returns the handle of the execution stream that is
* running the calling work unit through \c xstream.
*
* @contexts
* \DOC_CONTEXT_INIT_NOEXT \DOC_CONTEXT_NOCTXSWITCH
*
* @errors
* \DOC_ERROR_SUCCESS
* \DOC_ERROR_INV_XSTREAM_EXT
*
* @undefined
* \DOC_UNDEFINED_UNINIT
* \DOC_UNDEFINED_NULL_PTR{\c xstream}
* \DOC_UNDEFINED_UNINIT
*
* @param[out] xstream execution stream handle
* @return Error code
*/
int ABT_self_get_xstream(ABT_xstream *xstream)
{
ABTI_xstream *p_local_xstream;
ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);

/* Return value */
*xstream = ABTI_xstream_get_handle(p_local_xstream);
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Return a rank of an execution stream that is running the calling
* work unit.
*
* \c ABT_self_get_xstream_rank() returns the rank of the execution stream that
* is running the calling work unit through \c rank.
*
* @contexts
* \DOC_CONTEXT_INIT_NOEXT \DOC_CONTEXT_NOCTXSWITCH
*
* @errors
* \DOC_ERROR_SUCCESS
* \DOC_ERROR_INV_XSTREAM_EXT
*
* @undefined
* \DOC_UNDEFINED_UNINIT
* \DOC_UNDEFINED_NULL_PTR{\c rank}
* \DOC_UNDEFINED_UNINIT
*
* @param[out] rank execution stream rank
* @return Error code
*/
int ABT_self_get_xstream_rank(int *rank)
{
ABTI_xstream *p_local_xstream;
ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);
/* Return value */
*rank = (int)p_local_xstream->rank;
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Get the calling work unit.
*
* \c ABT_self_get_thread() returns the handle of the calling work unit through
* \c thread.
*
* @contexts
* \DOC_CONTEXT_INIT_NOEXT \DOC_CONTEXT_NOCTXSWITCH
*
* @errors
* \DOC_ERROR_SUCCESS
* \DOC_ERROR_INV_XSTREAM_EXT
*
* @undefined
* \DOC_UNDEFINED_NULL_PTR{\c thread}
* \DOC_UNDEFINED_UNINIT
*
* @param[out] thread work unit handle
* @return Error code
*/
int ABT_self_get_thread(ABT_thread *thread)
{
ABTI_xstream *p_local_xstream;
ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);
*thread = ABTI_thread_get_handle(p_local_xstream->p_thread);
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Get ID of the calling work unit.
*
* \c ABT_self_get_thread_id() returns the ID of the calling work unit through
* \c id.
*
* @contexts
* \DOC_CONTEXT_INIT_NOEXT \DOC_CONTEXT_NOCTXSWITCH
*
* @errors
* \DOC_ERROR_SUCCESS
* \DOC_ERROR_INV_XSTREAM_EXT
*
* @undefined
* \DOC_UNDEFINED_NULL_PTR{\c id}
* \DOC_UNDEFINED_UNINIT
*
* @param[out] id ID of the calling work unit
* @return Error code
*/
int ABT_self_get_thread_id(ABT_unit_id *id)
{
ABTI_xstream *p_local_xstream;
ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);
*id = ABTI_thread_get_id(p_local_xstream->p_thread);
return ABT_SUCCESS;
}

#ifdef ABT_CONFIG_USE_DOXYGEN
/**
* @ingroup SELF
* @brief Get the calling work unit.
*
* The functionality of this routine is the same as \c ABT_self_get_thread().
*/
int ABT_self_get_task(ABT_thread *thread);
#endif

#ifdef ABT_CONFIG_USE_DOXYGEN
/**
* @ingroup SELF
* @brief Get ID of the calling work unit.
*
* The functionality of this routine is the same as \c ABT_self_get_thread_id().
*/
int ABT_self_get_task_id(ABT_unit_id *id);
#endif

/**
* @ingroup SELF
* @brief Associate a value with a work-unit-specific 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
* units may bind different values to the same key.
*
* \DOC_DESC_ATOMICITY_WORK_UNIT_KEY
*
* @contexts
* \DOC_CONTEXT_INIT_NOEXT \DOC_CONTEXT_NOCTXSWITCH
*
* @errors
* \DOC_ERROR_SUCCESS
* \DOC_ERROR_INV_XSTREAM_EXT
* \DOC_ERROR_INV_KEY_HANDLE{\c key}
* \DOC_ERROR_RESOURCE
*
* @undefined
* \DOC_UNDEFINED_UNINIT
*
* @param[in] key work-unit-specific data key handle
* @param[in] value value associated with \c key
* @return Error code
*/
int ABT_self_set_specific(ABT_key key, void *value)
{
ABTI_key *p_key = ABTI_key_get_ptr(key);
ABTI_CHECK_NULL_KEY_PTR(p_key);

ABTI_global *p_global;
ABTI_SETUP_GLOBAL(&p_global);

ABTI_xstream *p_local_xstream;
ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);

/* Obtain the key-value table pointer. */
int abt_errno =
ABTI_ktable_set(p_global, ABTI_xstream_get_local(p_local_xstream),
&p_local_xstream->p_thread->p_keytable, p_key, value);
ABTI_CHECK_ERROR(abt_errno);
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Get a value associated with a 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 to \c NULL.
*
* \DOC_DESC_ATOMICITY_WORK_UNIT_KEY
*
* @contexts
* \DOC_CONTEXT_INIT_NOEXT \DOC_CONTEXT_NOCTXSWITCH
*
* @errors
* \DOC_ERROR_SUCCESS
* \DOC_ERROR_INV_XSTREAM_EXT
* \DOC_ERROR_INV_KEY_HANDLE{\c key}
*
* @undefined
* \DOC_UNDEFINED_NULL_PTR{\c value}
* \DOC_UNDEFINED_UNINIT
*
* @param[in] key work-unit-specific data key handle
* @param[out] value value associated with \c key
* @return Error code
*/
int ABT_self_get_specific(ABT_key key, void **value)
{
ABTI_key *p_key = ABTI_key_get_ptr(key);
ABTI_CHECK_NULL_KEY_PTR(p_key);

/* We don't allow an external thread to call this routine. */
ABTI_xstream *p_local_xstream;
ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);

/* Obtain the key-value table pointer */
*value = ABTI_ktable_get(&p_local_xstream->p_thread->p_keytable, p_key);
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Obtain a type of the caller.
Expand Down Expand Up @@ -231,6 +460,38 @@ int ABT_self_get_last_pool_id(int *pool_id)
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Yield the calling ULT to its parent ULT
*
* \c ABT_self_yield() yields the calling ULT and pushes the calling ULT to its
* associated pool. Its parent ULT will be resumed.
*
* @contexts
* \DOC_CONTEXT_INIT_YIELDABLE \DOC_CONTEXT_CTXSWITCH
*
* @errors
* \DOC_ERROR_SUCCESS
* \DOC_ERROR_INV_THREAD_NY
* \DOC_ERROR_INV_XSTREAM_EXT
*
* @undefined
* \DOC_UNDEFINED_UNINIT
* \DOC_UNDEFINED_THREAD_UNSAFE{the caller}
*
* @return Error code
*/
int ABT_self_yield(void)
{
ABTI_xstream *p_local_xstream;
ABTI_ythread *p_ythread;
ABTI_SETUP_LOCAL_YTHREAD(&p_local_xstream, &p_ythread);

ABTI_ythread_yield(&p_local_xstream, p_ythread, ABT_SYNC_EVENT_TYPE_USER,
NULL);
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Suspend the calling ULT.
Expand Down Expand Up @@ -272,6 +533,38 @@ int ABT_self_suspend(void)
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Terminate a calling ULT.
*
* \c ABT_self_exit() terminates the calling ULT. This routine does not return
* if it succeeds.
*
* @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{\c the caller}
*
* @undefined
* \DOC_UNDEFINED_UNINIT
*
* @return Error code
*/
int ABT_self_exit(void)
{
ABTI_xstream *p_local_xstream;
ABTI_ythread *p_ythread;
ABTI_SETUP_LOCAL_YTHREAD(&p_local_xstream, &p_ythread);
ABTI_CHECK_TRUE(!(p_ythread->thread.type & ABTI_THREAD_TYPE_PRIMARY),
ABT_ERR_INV_THREAD);

ABTI_ythread_exit(p_local_xstream, p_ythread);
return ABT_SUCCESS;
}

/**
* @ingroup SELF
* @brief Set an argument for a work-unit function of the calling work unit
Expand Down
6 changes: 6 additions & 0 deletions src/stream.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -588,6 +588,9 @@ int ABT_xstream_cancel(ABT_xstream xstream)
* \c ABT_xstream_self() returns the handle of the execution stream that is
* running the calling work unit through \c xstream.
*
* @note
* \DOC_DESC_REPLACEMENT{\c ABT_self_get_xstream()}
*
* @changev20
* \DOC_DESC_V1X_RETURN_UNINITIALIZED
*
Expand Down Expand Up @@ -631,6 +634,9 @@ int ABT_xstream_self(ABT_xstream *xstream)
* \c ABT_xstream_self_rank() returns the rank of the execution stream that is
* running the calling work unit through \c rank.
*
* @note
* \DOC_DESC_REPLACEMENT{\c ABT_self_get_xstream_rank()}
*
* @changev20
* \DOC_DESC_V1X_RETURN_UNINITIALIZED
* @endchangev20
Expand Down
Loading

0 comments on commit f816757

Please sign in to comment.