Merge pull request #319 from shintaro-iwasaki/pr/new_utility_apis

add new utility APIs

src/include/abt.h.in

@@ -1779,6 +1779,7 @@ int ABT_pool_add_sched(ABT_pool pool, ABT_sched sched) ABT_API_PUBLIC;
 int ABT_pool_get_id(ABT_pool pool, int *id) ABT_API_PUBLIC;
 
 /* Work Unit */
+int ABT_unit_get_thread(ABT_unit unit, ABT_thread *thread) ABT_API_PUBLIC;
 int ABT_unit_set_associated_pool(ABT_unit unit, ABT_pool pool) ABT_API_PUBLIC;
 
 /* User-level Thread (ULT) */
@@ -1805,6 +1806,7 @@ int ABT_thread_get_last_xstream(ABT_thread thread, ABT_xstream *xstream) ABT_API
 int ABT_thread_get_state(ABT_thread thread, ABT_thread_state *state) ABT_API_PUBLIC;
 int ABT_thread_get_last_pool(ABT_thread thread, ABT_pool *pool) ABT_API_PUBLIC;
 int ABT_thread_get_last_pool_id(ABT_thread thread, int *id) ABT_API_PUBLIC;
+int ABT_thread_get_unit(ABT_thread thread, ABT_unit *unit) ABT_API_PUBLIC;
 int ABT_thread_set_associated_pool(ABT_thread thread, ABT_pool pool) ABT_API_PUBLIC;
 int ABT_thread_yield_to(ABT_thread thread) ABT_API_PUBLIC;
 int ABT_thread_yield(void) ABT_API_PUBLIC;
@@ -1825,6 +1827,7 @@ int ABT_thread_get_stacksize(ABT_thread thread, size_t *stacksize) ABT_API_PUBLI
 int ABT_thread_get_id(ABT_thread thread, ABT_unit_id *thread_id) ABT_API_PUBLIC;
 int ABT_thread_set_arg(ABT_thread thread, void *arg) ABT_API_PUBLIC;
 int ABT_thread_get_arg(ABT_thread thread, void **arg) ABT_API_PUBLIC;
+int ABT_thread_get_thread_func(ABT_thread thread, void (**thread_func)(void *)) ABT_API_PUBLIC;
 int ABT_thread_set_specific(ABT_thread thread, ABT_key key, void *value) ABT_API_PUBLIC;
 int ABT_thread_get_specific(ABT_thread thread, ABT_key key, void **value) ABT_API_PUBLIC;
 int ABT_thread_get_attr(ABT_thread thread, ABT_thread_attr *attr) ABT_API_PUBLIC;
@@ -1880,12 +1883,16 @@ 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(ABT_pool *pool) ABT_API_PUBLIC;
 int ABT_self_get_last_pool_id(int *pool_id) ABT_API_PUBLIC;
+int ABT_self_set_associated_pool(ABT_pool pool) ABT_API_PUBLIC;
+int ABT_self_get_unit(ABT_unit *unit) 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;
+int ABT_self_get_thread_func(void (**thread_func)(void *)) ABT_API_PUBLIC;
 
 /* ULT-specific data */
 int ABT_key_create(void (*destructor)(void *value), ABT_key *newkey) ABT_API_PUBLIC;

src/self.c

@@ -412,6 +412,37 @@ int ABT_self_on_primary_xstream(ABT_bool *on_primary)
  return ABT_SUCCESS;
 }
 
+/**
+ * @ingroup SELF
+ * @brief Get the last pool of the calling work unit.
+ *
+ * \c ABT_self_get_last_pool() returns the last pool associated with the calling
+ * work unit through \c pool.
+ *
+ * @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 pool}
+ *
+ * @param[out] pool pool handle
+ * @return Error code
+ */
+int ABT_self_get_last_pool(ABT_pool *pool)
+{
+ ABTI_xstream *p_local_xstream;
+ ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);
+ ABTI_thread *p_self = p_local_xstream->p_thread;
+ ABTI_ASSERT(p_self->p_pool);
+ *pool = ABTI_pool_get_handle(p_self->p_pool);
+ return ABT_SUCCESS;
+}
+
 /**
  * @ingroup SELF
  * @brief Get ID of the last pool of the calling work unit.
@@ -459,6 +490,75 @@ int ABT_self_get_last_pool_id(int *pool_id)
  return ABT_SUCCESS;
 }
 
+/**
+ * @ingroup SELF
+ * @brief Set an associated pool for the calling work unit.
+ *
+ * \c ABT_self_set_associated_pool() changes the associated pool of the work
+ * unit \c thread to the pool \c pool. This routine does not yield the calling
+ * work unit.
+ *
+ * @contexts
+ * \DOC_CONTEXT_INIT_NOEXT \DOC_CONTEXT_NOCTXSWITCH
+ *
+ * @errors
+ * \DOC_ERROR_SUCCESS
+ * \DOC_ERROR_INV_XSTREAM_EXT
+ * \DOC_ERROR_INV_POOL_HANDLE{\c pool}
+ * \DOC_ERROR_RESOURCE
+ * \DOC_ERROR_RESOURCE_UNIT_CREATE
+ *
+ * @undefined
+ * \DOC_UNDEFINED_UNINIT
+ * \DOC_UNDEFINED_THREAD_UNSAFE{the caller}
+ *
+ * @param[in] pool pool handle
+ * @return Error code
+ */
+int ABT_self_set_associated_pool(ABT_pool pool)
+{
+ ABTI_global *p_global = ABTI_global_get_global();
+ ABTI_xstream *p_local_xstream;
+ ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);
+ ABTI_pool *p_pool = ABTI_pool_get_ptr(pool);
+ ABTI_CHECK_NULL_POOL_PTR(p_pool);
+ ABTI_thread *p_self = p_local_xstream->p_thread;
+
+ int abt_errno = ABTI_thread_set_associated_pool(p_global, p_self, p_pool);
+ ABTI_CHECK_ERROR(abt_errno);
+ return ABT_SUCCESS;
+}
+
+/**
+ * @ingroup SELF
+ * @brief Get a unit handle of the calling work unit.
+ *
+ * \c ABT_self_get_unit() returns the \c ABT_unit handle associated with the
+ * calling work unit through \c unit.
+ *
+ * @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 unit}
+ *
+ * @param[out] unit work unit handle
+ * @return Error code
+ */
+int ABT_self_get_unit(ABT_unit *unit)
+{
+ /* We don't allow an external thread to call this routine. */
+ ABTI_xstream *p_local_xstream;
+ ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);
+ *unit = p_local_xstream->p_thread->unit;
+ return ABT_SUCCESS;
+}
+
 /**
  * @ingroup SELF
  * @brief Yield the calling ULT to its parent ULT
@@ -647,6 +747,36 @@ int ABT_self_get_arg(void **arg)
  return ABT_SUCCESS;
 }
 
+/**
+ * @ingroup SELF
+ * @brief Retrieve a work-unit function of the calling work unit
+ *
+ * \c ABT_self_get_thread_func() returns the work-unit function of the calling
+ * work unit through \c thread_func.
+ *
+ * @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 thread_func}
+ *
+ * @param[out] thread_func the caller's function
+ * @return Error code
+ */
+int ABT_self_get_thread_func(void (**thread_func)(void *))
+{
+ ABTI_xstream *p_local_xstream;
+ ABTI_SETUP_LOCAL_XSTREAM(&p_local_xstream);
+
+ *thread_func = p_local_xstream->p_thread->f_thread;
+ return ABT_SUCCESS;
+}
+
 /**
  * @ingroup SELF
  * @brief Check if the calling work unit is unnamed

src/thread.c

@@ -935,6 +935,36 @@ int ABT_thread_get_last_pool_id(ABT_thread thread, int *id)
  return ABT_SUCCESS;
 }
 
+/**
+ * @ingroup ULT
+ * @brief Get a unit handle of the target work unit.
+ *
+ * \c ABT_thread_get_unit() returns the \c ABT_unit handle associated with the
+ * work unit \c thread through \c unit.
+ *
+ * @contexts
+ * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH
+ *
+ * @errors
+ * \DOC_ERROR_SUCCESS
+ * \DOC_ERROR_INV_THREAD_HANDLE{\c thread}
+ *
+ * @undefined
+ * \DOC_UNDEFINED_UNINIT
+ * \DOC_UNDEFINED_NULL_PTR{\c unit}
+ *
+ * @param[in] thread work unit handle
+ * @param[out] unit work unit handle
+ * @return Error code
+ */
+int ABT_thread_get_unit(ABT_thread thread, ABT_unit *unit)
+{
+ ABTI_thread *p_thread = ABTI_thread_get_ptr(thread);
+ ABTI_CHECK_NULL_THREAD_PTR(p_thread);
+ *unit = p_thread->unit;
+ return ABT_SUCCESS;
+}
+
 /**
  * @ingroup ULT
  * @brief Set an associated pool for the target work unit.
@@ -2021,6 +2051,37 @@ int ABT_thread_get_arg(ABT_thread thread, void **arg)
  return ABT_SUCCESS;
 }
 
+/**
+ * @ingroup ULT
+ * @brief Retrieve a work-unit function of a work unit.
+ *
+ * \c ABT_thread_get_thread_func() returns the work-unit function of the work
+ * unit \c thread through \c thread_func.
+ *
+ * @contexts
+ * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH
+ *
+ * @errors
+ * \DOC_ERROR_SUCCESS
+ * \DOC_ERROR_INV_THREAD_HANDLE{\c thread}
+ *
+ * @undefined
+ * \DOC_UNDEFINED_UNINIT
+ * \DOC_UNDEFINED_NULL_PTR{\c thread_func}
+ *
+ * @param[in] thread work unit handle
+ * @param[out] thread_func work-unit function
+ * @return Error code
+ */
+int ABT_thread_get_thread_func(ABT_thread thread, void (**thread_func)(void *))
+{
+ ABTI_thread *p_thread = ABTI_thread_get_ptr(thread);
+ ABTI_CHECK_NULL_THREAD_PTR(p_thread);
+
+ *thread_func = p_thread->f_thread;
+ return ABT_SUCCESS;
+}
+
 /**
  * @ingroup ULT
  * @brief Set a value with a work-unit-specific data key in a work unit.

src/unit.c

@@ -53,6 +53,37 @@ int ABT_unit_set_associated_pool(ABT_unit unit, ABT_pool pool)
  return ABT_SUCCESS;
 }
 
+/**
+ * @ingroup UNIT
+ * @brief Get a thread handle of the target work unit.
+ *
+ * \c ABT_unit_get_thread() returns the \c ABT_thread handle associated with the
+ * work unit \c unit through \c thread.
+ *
+ * @contexts
+ * \DOC_CONTEXT_INIT \DOC_CONTEXT_NOCTXSWITCH
+ *
+ * @errors
+ * \DOC_ERROR_SUCCESS
+ * \DOC_ERROR_INV_UNIT_HANDLE{\c unit}
+ *
+ * @undefined
+ * \DOC_UNDEFINED_UNINIT
+ * \DOC_UNDEFINED_NULL_PTR{\c thread}
+ *
+ * @param[in] unit work unit handle
+ * @param[out] thread work unit handle
+ * @return Error code
+ */
+int ABT_unit_get_thread(ABT_unit unit, ABT_thread *thread)
+{
+ ABTI_global *p_global = ABTI_global_get_global();
+ ABTI_CHECK_TRUE(unit != ABT_UNIT_NULL, ABT_ERR_INV_UNIT);
+ ABTI_thread *p_thread = ABTI_unit_get_thread(p_global, unit);
+ *thread = ABTI_thread_get_handle(p_thread);
+ return ABT_SUCCESS;
+}
+
 /*****************************************************************************/
 /* Private APIs */
 /*****************************************************************************/

test/.gitignore

@@ -17,6 +17,7 @@ basic/thread_yield_to
 basic/thread_exit
 basic/thread_self_suspend_resume
 basic/thread_get_last_xstream
+basic/thread_get_func_arg
 basic/thread_migrate
 basic/thread_data
 basic/thread_data2
@@ -75,6 +76,7 @@ basic/info_print
 basic/info_print_stack
 basic/info_stackdump
 basic/info_stackdump2
+basic/unit
 basic/error
 
 # benchmark

test/basic/Makefile.am

@@ -22,6 +22,7 @@ TESTS = \
  thread_exit \
  thread_self_suspend_resume \
  thread_get_last_xstream \
+ thread_get_func_arg \
  thread_migrate \
  thread_data \
  thread_data2 \
@@ -80,6 +81,7 @@ TESTS = \
  info_print_stack \
  info_stackdump \
  info_stackdump2 \
+ unit \
  error
 
 XFAIL_TESTS =
@@ -115,6 +117,7 @@ thread_yield_to_SOURCES = thread_yield_to.c
 thread_exit_SOURCES = thread_exit.c
 thread_self_suspend_resume_SOURCES = thread_self_suspend_resume.c
 thread_get_last_xstream_SOURCES = thread_get_last_xstream.c
+thread_get_func_arg_SOURCES = thread_get_func_arg.c
 thread_migrate_SOURCES = thread_migrate.c
 thread_data_SOURCES = thread_data.c
 thread_data2_SOURCES = thread_data2.c
@@ -173,6 +176,7 @@ info_print_SOURCES = info_print.c
 info_print_stack_SOURCES = info_print_stack.c
 info_stackdump_SOURCES = info_stackdump.c
 info_stackdump2_SOURCES = info_stackdump2.c
+unit_SOURCES = unit.c
 error_SOURCES = error.c
 
 testing:
@@ -194,6 +198,7 @@ testing:
  ./thread_exit
  ./thread_self_suspend_resume
  ./thread_get_last_xstream
+ ./thread_get_func_arg
  ./thread_migrate
  ./thread_data
  ./thread_data2
@@ -252,4 +257,5 @@ testing:
  ./info_print_stack
  ./info_stackdump
  ./info_stackdump2
+ ./unit
  ./error

test/basic/pool_custom.c

@@ -25,12 +25,9 @@ void thread_func(void *arg)
  for (i = 0; i < 10; i++) {
  if (i % 3 == 0) {
  ABT_pool target_pool = (ABT_pool)arg;
- ABT_thread thread;
- ret = ABT_self_get_thread(&thread);
- ATS_ERROR(ret, "ABT_self_get_thread");
  /* Let's change the associated pool sometimes. */
- ret = ABT_thread_set_associated_pool(thread, target_pool);
- ATS_ERROR(ret, "ABT_thread_set_associated_pool");
+ ret = ABT_self_set_associated_pool(target_pool);
+ ATS_ERROR(ret, "ABT_self_set_associated_pool");
  }
  ret = ABT_thread_yield();
  ATS_ERROR(ret, "ABT_thread_yield");
@@ -227,12 +224,8 @@ int main(int argc, char *argv[])
 
  /* Move this thread to the main pool. This is needed since the following
  * user-defined pool_free() checks whether the pool is empty or not. */
- ABT_thread self_thread;
- ret = ABT_self_get_thread(&self_thread);
- ATS_ERROR(ret, "ABT_thread_self");
- /* Let's change the associated pool sometimes. */
- ret = ABT_thread_set_associated_pool(self_thread, pools[0]);
- ATS_ERROR(ret, "ABT_thread_set_associated_pool");
+ ret = ABT_self_set_associated_pool(pools[0]);
+ ATS_ERROR(ret, "ABT_self_set_associated_pool");
 
  /* Free schedulers of the secondary execution streams (since the scheduler
  * created by ABT_sched_create() are not automatically freed). */