ARGOBOTS  66b1c39742507d8df30e8d28c54839b961a14814
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Functions
Execution Stream (ES)

Functions

int ABT_xstream_create (ABT_sched sched, ABT_xstream *newxstream)
 Create a new ES and return its handle through newxstream. More...
 
int ABT_xstream_create_basic (ABT_sched_predef predef, int num_pools, ABT_pool *pools, ABT_sched_config config, ABT_xstream *newxstream)
 Create a new ES with a predefined scheduler and return its handle through newxstream. More...
 
int ABT_xstream_create_with_rank (ABT_sched sched, int rank, ABT_xstream *newxstream)
 Create a new ES with a specific rank. More...
 
int ABT_xstream_revive (ABT_xstream xstream)
 Restart an ES that has been joined by ABT_xstream_join(). More...
 
int ABT_xstream_free (ABT_xstream *xstream)
 Release the ES object associated with ES handle. More...
 
int ABT_xstream_join (ABT_xstream xstream)
 Wait for xstream to terminate. More...
 
int ABT_xstream_exit (void)
 Terminate the ES associated with the calling ULT. More...
 
int ABT_xstream_cancel (ABT_xstream xstream)
 Request the cancellation of the target ES. More...
 
int ABT_xstream_self (ABT_xstream *xstream)
 Return the ES handle associated with the caller work unit. More...
 
int ABT_xstream_self_rank (int *rank)
 Return the rank of ES associated with the caller work unit. More...
 
int ABT_xstream_set_rank (ABT_xstream xstream, int rank)
 Set the rank for target ES. More...
 
int ABT_xstream_get_rank (ABT_xstream xstream, int *rank)
 Return the rank of ES. More...
 
int ABT_xstream_set_main_sched (ABT_xstream xstream, ABT_sched sched)
 Set the main scheduler of the target ES. More...
 
int ABT_xstream_set_main_sched_basic (ABT_xstream xstream, ABT_sched_predef predef, int num_pools, ABT_pool *pools)
 Set the main scheduler for xstream with a predefined scheduler. More...
 
int ABT_xstream_get_main_sched (ABT_xstream xstream, ABT_sched *sched)
 Get the main scheduler of the target ES. More...
 
int ABT_xstream_get_main_pools (ABT_xstream xstream, int max_pools, ABT_pool *pools)
 Get the pools of the main scheduler of the target ES. More...
 
int ABT_xstream_get_state (ABT_xstream xstream, ABT_xstream_state *state)
 Return the state of xstream. More...
 
int ABT_xstream_equal (ABT_xstream xstream1, ABT_xstream xstream2, ABT_bool *result)
 Compare two ES handles for equality. More...
 
int ABT_xstream_get_num (int *num_xstreams)
 Return the number of current existing ESs. More...
 
int ABT_xstream_is_primary (ABT_xstream xstream, ABT_bool *flag)
 Check if the target ES is the primary ES. More...
 
int ABT_xstream_run_unit (ABT_unit unit, ABT_pool pool)
 Execute a unit on the local ES. More...
 
int ABT_xstream_check_events (ABT_sched sched)
 Check the events and process them. More...
 
int ABT_xstream_set_cpubind (ABT_xstream xstream, int cpuid)
 Bind the target ES to a target CPU. More...
 
int ABT_xstream_get_cpubind (ABT_xstream xstream, int *cpuid)
 Get the CPU binding for the target ES. More...
 
int ABT_xstream_set_affinity (ABT_xstream xstream, int cpuset_size, int *cpuset)
 Set the CPU affinity of the target ES. More...
 
int ABT_xstream_get_affinity (ABT_xstream xstream, int cpuset_size, int *cpuset, int *num_cpus)
 Get the CPU affinity for the target ES. More...
 

Detailed Description

This group is for Execution Stream.

Function Documentation

int ABT_xstream_cancel ( ABT_xstream  xstream)

Request the cancellation of the target ES.

Parameters
[in]xstreamhandle to the target ES
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 309 of file stream.c.

int ABT_xstream_check_events ( ABT_sched  sched)

Check the events and process them.

This function must be called by a scheduler periodically. Therefore, a user will use it on his own defined scheduler.

Parameters
[in]schedhandle to the scheduler where this call is from
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_INV_XSTREAMcalled by an external thread

Definition at line 709 of file stream.c.

int ABT_xstream_create ( ABT_sched  sched,
ABT_xstream newxstream 
)

Create a new ES and return its handle through newxstream.

Parameters
[in]schedhandle to the scheduler used for a new ES. If this is ABT_SCHED_NULL, the runtime-provided scheduler is used.
[out]newxstreamhandle to a newly created ES. This cannot be NULL because unnamed ES is not allowed.
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 46 of file stream.c.

int ABT_xstream_create_basic ( ABT_sched_predef  predef,
int  num_pools,
ABT_pool pools,
ABT_sched_config  config,
ABT_xstream newxstream 
)

Create a new ES with a predefined scheduler and return its handle through newxstream.

If predef is a scheduler that includes automatic creation of pools, pools will be equal to NULL.

Parameters
[in]predefpredefined scheduler
[in]num_poolsnumber of pools associated with this scheduler
[in]poolspools associated with this scheduler
[in]configspecific config used during the scheduler creation
[out]newxstreamhandle to the target ES
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 91 of file stream.c.

int ABT_xstream_create_with_rank ( ABT_sched  sched,
int  rank,
ABT_xstream newxstream 
)

Create a new ES with a specific rank.

Parameters
[in]schedhandle to the scheduler used for a new ES. If this is ABT_SCHED_NULL, the runtime-provided scheduler is used.
[in]ranktarget rank
[out]newxstreamhandle to a newly created ES. This cannot be NULL because unnamed ES is not allowed.
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_INV_XSTREAM_RANKinvalid rank

Definition at line 128 of file stream.c.

int ABT_xstream_equal ( ABT_xstream  xstream1,
ABT_xstream  xstream2,
ABT_bool result 
)

Compare two ES handles for equality.

ABT_xstream_equal() compares two ES handles for equality. If two handles are associated with the same ES, result will be set to ABT_TRUE. Otherwise, result will be set to ABT_FALSE.

Parameters
[in]xstream1handle to the ES 1
[in]xstream2handle to the ES 2
[out]resultcomparison result (ABT_TRUE: same, ABT_FALSE: not same)
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 611 of file stream.c.

int ABT_xstream_exit ( void  )

Terminate the ES associated with the calling ULT.

Since the calling ULT's ES terminates, this routine never returns. Tasklets are not allowed to call this routine.

Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_UNINITIALIZEDArgobots has not been initialized
ABT_ERR_INV_XSTREAMcalled by an external thread
ABT_ERR_INV_THREADcalled by a non-yieldable thread (tasklet)

Definition at line 285 of file stream.c.

int ABT_xstream_free ( ABT_xstream xstream)

Release the ES object associated with ES handle.

This routine deallocates memory used for the ES object. If the xstream is still running when this routine is called, the deallocation happens after the xstream terminates and then this routine returns. If it is successfully processed, xstream is set as ABT_XSTREAM_NULL. The primary ES cannot be freed with this routine.

Parameters
[in,out]xstreamhandle to the target ES
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 217 of file stream.c.

int ABT_xstream_get_affinity ( ABT_xstream  xstream,
int  cpuset_size,
int *  cpuset,
int *  num_cpus 
)

Get the CPU affinity for the target ES.

ABT_xstream_get_cpubind() writes CPU IDs (at most, cpuset_size) to cpuset and returns the number of elements written to cpuset to num_cpus. If num_cpus is NULL, it is ignored.

If cpuset is NULL, cpuset_size is ignored and the nubmer of all CPUs on which xstream is bound is returned through num_cpus. Otherwise, i.e., if cpuset is NULL, cpuset_size must be greater than zero.

Parameters
[in]xstreamhandle to the target ES
[in]cpuset_sizethe number of cpuset entries
[out]cpusetarray of CPU IDs
[out]num_cpusthe number of total CPU IDs
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 831 of file stream.c.

int ABT_xstream_get_cpubind ( ABT_xstream  xstream,
int *  cpuid 
)

Get the CPU binding for the target ES.

ABT_xstream_get_cpubind() returns the ID of CPU, which the target ES xstream is bound to. If xstream is bound to more than one CPU, only the first CPU ID is returned.

Parameters
[in]xstreamhandle to the target ES
[out]cpuidCPU ID
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 761 of file stream.c.

int ABT_xstream_get_main_pools ( ABT_xstream  xstream,
int  max_pools,
ABT_pool pools 
)

Get the pools of the main scheduler of the target ES.

This function is a convenient function that retrieves the associated pools of the main scheduler.

Parameters
[in]xstreamhandle to the target ES
[in]max_poolsmaximum number of pools
[out]poolsarray of handles to the pools
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 566 of file stream.c.

int ABT_xstream_get_main_sched ( ABT_xstream  xstream,
ABT_sched sched 
)

Get the main scheduler of the target ES.

ABT_xstream_get_main_sched() gets the handle of the main scheduler for the target ES xstream through sched.

Parameters
[in]xstreamhandle to the target ES
[out]schedhandle to the scheduler
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 544 of file stream.c.

int ABT_xstream_get_num ( int *  num_xstreams)

Return the number of current existing ESs.

ABT_xstream_get_num() returns the number of ESs that exist in the current Argobots environment through num_xstreams.

Parameters
[out]num_xstreamsthe number of ESs
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_UNINITIALIZEDArgobots has not been initialized

Definition at line 632 of file stream.c.

int ABT_xstream_get_rank ( ABT_xstream  xstream,
int *  rank 
)

Return the rank of ES.

Parameters
[in]xstreamhandle to the target ES
[out]rankES rank
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 405 of file stream.c.

int ABT_xstream_get_state ( ABT_xstream  xstream,
ABT_xstream_state state 
)

Return the state of xstream.

Parameters
[in]xstreamhandle to the target ES
[out]statethe xstream's state
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 587 of file stream.c.

int ABT_xstream_is_primary ( ABT_xstream  xstream,
ABT_bool flag 
)

Check if the target ES is the primary ES.

ABT_xstream_is_primary() checks whether the target ES is the primary ES. If the ES xstream is the primary ES, flag is set to ABT_TRUE. Otherwise, flag is set to ABT_FALSE.

Parameters
[in]xstreamhandle to the target ES
[out]flagresult (ABT_TRUE: primary ES, ABT_FALSE: not)
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 656 of file stream.c.

int ABT_xstream_join ( ABT_xstream  xstream)

Wait for xstream to terminate.

The target xstream cannot be the same as the xstream associated with calling thread. If they are identical, this routine returns immediately without waiting for the xstream's termination.

Parameters
[in]xstreamhandle to the target ES
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 261 of file stream.c.

int ABT_xstream_revive ( ABT_xstream  xstream)

Restart an ES that has been joined by ABT_xstream_join().

Parameters
[in]xstreamhandle to an ES that has been joined but not freed.
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 173 of file stream.c.

int ABT_xstream_run_unit ( ABT_unit  unit,
ABT_pool  pool 
)

Execute a unit on the local ES.

This function can be called by a scheduler after picking one unit. So a user will use it for his own defined scheduler.

EXPERIMENTAL: this function can be called by a normal ULT, too. The function name could be changed in the future.

Parameters
[in]unithandle to the unit to run
[in]poolpool where unit is from
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_INV_XSTREAMcalled by an external thread
ABT_ERR_INV_THREADcalled by a non-yieldable thread (tasklet)

Definition at line 686 of file stream.c.

int ABT_xstream_self ( ABT_xstream xstream)

Return the ES handle associated with the caller work unit.

ABT_xstream_self() returns the handle to ES object associated with the caller work unit through xstream.

At present xstream is set to ABT_XSTREAM_NULL when an error occurs, but this behavior is deprecated. The program should not rely on this behavior.

Parameters
[out]xstreamES handle
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_UNINITIALIZEDArgobots has not been initialized
ABT_ERR_INV_XSTREAMcalled by an external thread

Definition at line 341 of file stream.c.

int ABT_xstream_self_rank ( int *  rank)

Return the rank of ES associated with the caller work unit.

Parameters
[out]rankES rank
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_UNINITIALIZEDArgobots has not been initialized
ABT_ERR_INV_XSTREAMcalled by an external thread, e.g., pthread

Definition at line 363 of file stream.c.

int ABT_xstream_set_affinity ( ABT_xstream  xstream,
int  cpuset_size,
int *  cpuset 
)

Set the CPU affinity of the target ES.

ABT_xstream_set_cpubind() binds the target ES xstream on the given CPU set, cpuset, which is an array of CPU IDs. Here, the CPU IDs correspond to processor indexes used by OS.

Parameters
[in]xstreamhandle to the target ES
[in]cpuset_sizethe number of cpuset entries
[in]cpusetarray of CPU IDs
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 797 of file stream.c.

int ABT_xstream_set_cpubind ( ABT_xstream  xstream,
int  cpuid 
)

Bind the target ES to a target CPU.

ABT_xstream_set_cpubind() binds the target ES xstream to the target CPU whose ID is cpuid. Here, the CPU ID corresponds to the processor index used by OS.

Parameters
[in]xstreamhandle to the target ES
[in]cpuidCPU ID
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 734 of file stream.c.

int ABT_xstream_set_main_sched ( ABT_xstream  xstream,
ABT_sched  sched 
)

Set the main scheduler of the target ES.

ABT_xstream_set_main_sched() sets sched as the main scheduler for xstream. The scheduler sched will first run when the ES xstream is started. Only ULTs can call this routine. If xstream is a handle to the primary ES, sched will be automatically freed on ABT_finalize() or when the main scheduler of the primary ES is changed again. In this case, the explicit call ABT_sched_free() for sched may cause undefined behavior.

NOTE: The current implementation of this routine has some limitations.

  1. If the target ES xstream is running, the caller ULT must be running on the same ES. However, if the target ES is not in the RUNNING state, the caller can be any ULT that is running on any ES.
  2. If the current main scheduler of xstream has work units residing in its associated pools, this routine will not be successful. In this case, the user has to complete all work units in the main scheduler's pools or migrate them to unassociated pools.
Parameters
[in]xstreamhandle to the target ES
[in]schedhandle to the scheduler
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_XSTREAMthe current main scheduler of xstream has work units in its associated pools
ABT_ERR_INV_XSTREAMcalled by an external thread
ABT_ERR_INV_THREADcalled by a non-yieldable thread (tasklet)

Definition at line 444 of file stream.c.

int ABT_xstream_set_main_sched_basic ( ABT_xstream  xstream,
ABT_sched_predef  predef,
int  num_pools,
ABT_pool pools 
)

Set the main scheduler for xstream with a predefined scheduler.

See ABT_xstream_set_main_sched() for more details.

Parameters
[in]xstreamhandle to the target ES
[in]predefpredefined scheduler
[in]num_poolsnumber of pools associated with this scheduler
[in]poolspools associated with this scheduler
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_INV_XSTREAMcalled by an external thread
ABT_ERR_INV_THREADcalled by a non-yieldable thread (tasklet)

Definition at line 510 of file stream.c.

int ABT_xstream_set_rank ( ABT_xstream  xstream,
int  rank 
)

Set the rank for target ES.

Parameters
[in]xstreamhandle to the target ES
[in]rankES rank
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 382 of file stream.c.