/home/tau/parallel2/sys/src/mth/massivethreads/include/myth/myth.h

# myth.h

Summary

myth.h |
Functions |
myth_init | Initialize MassiveThreads library with default parameters (see myth_init_ex).
myth_init_ex | Initialize MassiveThreads library with the specified global attributes.
myth_fini | Finalize MassiveThreads.
myth_globalattr_init |
myth_globalattr_destroy |
myth_globalattr_get_stacksize |
myth_globalattr_set_stacksize |
myth_globalattr_get_n_workers |
myth_globalattr_set_n_workers |
myth_globalattr_get_bind_workers |
myth_globalattr_set_bind_workers |
myth_create | Create a new user-level thread executing func(arg) with default options.
myth_create_ex | Create a new user-level thread executing func(arg) with specified options.
myth_exit | Terminate the calling user-level thread.
myth_join | Wait for the specified thread th to finish.
myth_create_join_many_ex | Create many user-level threads executing the same function with various arguments and attributes and wait for them to complete.
myth_create_join_various_ex | Create many user-level threads executing various functions with various arguments and attributes and wait for them to complete.
myth_detach |
myth_is_myth_worker | 1 if the calling OS-level thread is a massivethreads worker.
myth_self | The identifier of the calling thread.
myth_equal |
myth_thread_attr_init |
myth_thread_attr_getdetachstate |
myth_thread_attr_setdetachstate |
myth_thread_attr_getguardsize |
myth_thread_attr_setguardsize |
myth_thread_attr_getstacksize |
myth_thread_attr_setstacksize |
myth_thread_attr_getstack |
myth_thread_attr_setstack |
myth_getattr_default_np |
myth_getattr_np |
myth_getconcurrency |
myth_yield_ex | Yield execution to another user-level thread.
myth_yield | it is equivalent to myth_yield_ex(myth_yield_option_half_half); with probability 1/2, try to yield to a thread in the local queue and if none is found try to steal a thread from a remote queue.
myth_setcancelstate |
myth_setcanceltype |
myth_cancel |
myth_testcancel |
Types |
myth_once_t |
Functions |
myth_once |
myth_mutex_init | Initialize a mutex.
myth_mutex_destroy | Destroy a mutex.
myth_mutex_trylock | Try to lock a mutex.
myth_mutex_lock | Lock a mutex.
myth_mutex_timedlock | Lock a mutex.
myth_mutex_unlock | Unlock a mutex.
myth_mutexattr_init |
myth_mutexattr_destroy |
myth_mutexattr_gettype |
myth_mutexattr_settype |
myth_rwlock_init |
myth_rwlock_destroy |
myth_rwlock_rdlock |
myth_rwlock_tryrdlock |
myth_rwlock_timedrdlock |
myth_rwlock_wrlock |
myth_rwlock_trywrlock |
myth_rwlock_timedwrlock |
myth_rwlock_unlock |
myth_rwlockattr_init |
myth_rwlockattr_destroy |
myth_rwlockattr_getkind |
myth_rwlockattr_setkind |
myth_cond_init | Initialize a condition variable.
myth_cond_destroy | Destroy a condition variable.
myth_cond_signal | Wake up at least one thread blocking on a condition variable.
myth_cond_broadcast | Wake up all threads blocking on a condition variable.
myth_cond_wait | Atomically unlock a mutex and block on a condition variable.
myth_cond_timedwait |
myth_condattr_init |
myth_condattr_destroy |
myth_barrier_init | Initialize a barrier.
myth_barrier_destroy | Destroy a barrier.
myth_barrier_wait | Wait on a barrier.
myth_barrierattr_init |
myth_barrierattr_destroy |
myth_join_counter_init |
myth_join_counter_wait |
myth_join_counter_dec |
myth_join_counterattr_init |
myth_join_counterattr_destroy |
myth_felock_init |
myth_felock_destroy |
myth_felock_lock |
myth_felock_unlock |
myth_felock_wait_and_lock |
myth_felock_mark_and_signal |
myth_felock_status |
myth_felockattr_init |
myth_felockattr_destroy |
myth_uncond_init | initialize an uncondition variable.
myth_uncond_destroy | destroy an uncondition variable.
myth_uncond_wait | block on an uncondition variable, to be waken up later by myth_uncond_signal.
myth_uncond_signal | unblock the thread blocking on uncond.
myth_key_create | Create a key for user-level thread-specific data.
myth_key_delete | Delete a key for user-level thread-specific data.
myth_setspecific | Associate a thread-specific data with a key.
myth_getspecific | Obtain a user-level thread-specific data associated with a key.
myth_get_worker_num | The index of the calling thread, an integer x satisfying 0 <= x < myth_get_num_workers().
myth_get_num_workers | The number of underlying workers.
myth_wls_key_create | Create a key for worker-specific data.
myth_wls_key_delete | Delete a key for worker-specific data.
myth_wls_setspecific | Associate a worker-specific data with a key.
myth_wls_getspecific | Obtain a worker-specific data associated with a key.
myth_sched_yield |
myth_sleep |
myth_usleep |
myth_nanosleep |

### Functions

### myth_init

> int myth_init( | void | )

Initialize MassiveThreads library with default parameters (see myth_init_ex). You normally do not have to call it by youself, as it is automatically called when you first call any MassiveThreads function. Internally, it invokes underlying workers. You may want to call it to make absolutely sure that an initilization has taken place before a certain point.

#### Returns

zero if the library has been successfully initialized. non-zero otherwise.

#### See Also

myth_init_ex

### myth_init_ex

> int myth_init_ex( | myth_globalattr_t | * | attr | )

Initialize MassiveThreads library with the specified global attributes. You normally do not have to call it by youself, as myth_init is automatically called when you first call any MassiveThreads function. You may want to call it to explicitly set various attributes.

#### Parameters

attr | the pointer to global attribute

#### Returns

zero if the library has been successfully initialized. non-zero otherwise.

#### See Also

myth_init, myth_create, myth_create_ex

### myth_fini

> void myth_fini( | void | )

Finalize MassiveThreads.

See Also: myth_init, myth_init_ex

### myth_globalattr_init

> int myth_globalattr_init( | myth_globalattr_t | * | attr | )

#### Parameters

attr | global attribute to initialize

initialize global attributes of MassiveThreads to default values. you can then set various attributes using one of myth_globalattr_set_ATTRIBUTE functions.

See Also: myth_init_ex, myth_globalattr_destroy, myth_globalattr_get_stacksize, myth_globalattr_set_stacksize, myth_globalattr_get_n_workers, myth_globalattr_set_n_workers, myth_globalattr_get_bind_workers, myth_globalattr_set_bind_workers

### myth_globalattr_destroy

> int myth_globalattr_destroy( | myth_globalattr_t | * | attr | )

#### Parameters

attr | global attribute to destroy

destroy global attributes of MassiveThreads.

See Also: myth_init, myth_init_ex, myth_globalattr_init

### myth_globalattr_get_stacksize

> int myth_globalattr_get_stacksize( | myth_globalattr_t | * | attr,
> | size_t | * | stacksize | )

#### Parameters

attr | global attribute to get stack size of
stacksize | address to get the result in

get the stack size attribute in attr, set either by myth_globalattr_init or myth_globalattr_set_stacksize

#### See Also

myth_globalattr_init, myth_globalattr_set_stacksize

### myth_globalattr_set_stacksize

> int myth_globalattr_set_stacksize( | myth_globalattr_t | * | attr,
> | size_t |  | stacksize | )

#### Parameters

attr | global attribute to set stack size of
stacksize | the stack size to set

set the stack size attribute in attr to the specified stacksize.

#### See Also

myth_globalattr_init, myth_globalattr_get_stacksize

### myth_globalattr_get_n_workers

> int myth_globalattr_get_n_workers( | myth_globalattr_t | * | attr,
> | size_t | * | n_workers | )

#### Parameters

attr | global attribute to get the number of workers of
n_workers | the address to get the number of workers in

get the number of workers attribute in attr, set either by myth_globalattr_init or myth_globalattr_set_n_workers

#### See Also

myth_globalattr_init, myth_globalattr_set_n_workers

### myth_globalattr_set_n_workers

> int myth_globalattr_set_n_workers( | myth_globalattr_t | * | attr,
> | size_t |  | n_workers | )

#### Parameters

attr | global attribute to set the number of workers of
n_workers | the number of workers

set the number of workers attribute of attr

#### See Also

myth_globalattr_init, myth_globalattr_get_n_workers

### myth_globalattr_get_bind_workers

> int myth_globalattr_get_bind_workers( | myth_globalattr_t | * | attr,
> | int | * | bind_workers | )

#### Parameters

attr | global attribute to get the bind_workers attribute of
bind_workers | the address to get the bind_workers attribute in

get the bind_workers attribute in attr, set either by myth_globalattr_init or myth_globalattr_set_bind_workers

#### See Also

myth_globalattr_init, myth_globalattr_set_bind_workers

### myth_globalattr_set_bind_workers

> int myth_globalattr_set_bind_workers( | myth_globalattr_t | * | attr,
> | int |  | bind_workers | )

#### Parameters

attr | global attribute to set the bind_workers attribute of
bind_workers | 1 or 0. 1 specified each worker should be bound to a core.

set the bind_workers attribute of attr

#### See Also

myth_globalattr_init, myth_globalattr_get_bind_workers

### myth_create

> myth_thread_t myth_create( | myth_func_t |  | func,
> | void | * | arg | )

Create a new user-level thread executing func(arg) with default options. Note that it is equivalent to myth_create_ex(func,arg,0);

#### Parameters

func | a pointer to a function.
arg | a pointer given to func.

#### Returns

The identifier of the newly created user-level thread.

#### Bug

Should any error occur, it terminates the program rather than returning an error code.

#### See Also

myth_create_ex, myth_join

### myth_create_ex

> int myth_create_ex( | myth_thread_t | * | id,
> | myth_thread_attr_t | * | attr,
> | myth_func_t |  | func,
> | void | * | arg | )

Create a new user-level thread executing func(arg) with specified options.

#### Parameters

id | a pointer, if not NULL, to which id of the created thread will be stored.
func | a pointer to a function.
arg | a pointer given to func.
attr | a pointer to a data structure of type <myth_thread_attr_t> specifying thread attributes, or NULL to mean the deafult.

#### Returns

0 if succeed.

#### Bug

Should any error occur, it terminates the program rather than returning an error code.

#### See Also

myth_create, myth_join, <myth_thread_option>

### myth_exit

> void myth_exit( | void | * | ret | )

Terminate the calling user-level thread.

#### Parameters

ret | exit value of the thread, which can be retrieved by calling myth_join on this thread.

#### See Also

myth_join

### myth_join

> int myth_join( | myth_thread_t |  | th,
> | void | ** | result | )

Wait for the specified thread th to finish.

#### Parameters

th | the identifier of the thread to wait for
result | a pointer to a data structure receiving the exit value of the thread, as determined by myth_exit or the return value of the thread’s main function.

#### See Also

myth_create, myth_create_ex

### myth_create_join_many_ex

> int myth_create_join_many_ex( | myth_thread_t | * | ids,
> | myth_thread_attr_t | * | attrs,
> | myth_func_t |  | func,
> | void | * | args,
> | void | * | results,
> | size_t |  | id_stride,
> | size_t |  | attr_stride,
> | size_t |  | arg_stride,
> | size_t |  | result_stride,
> | long |  | nthreads | )

Create many user-level threads executing the same function with various arguments and attributes and wait for them to complete.

#### Parameters

ids | base pointer to a (strided) array, to which thread ids of the created threads wll be stored (may be NULL)
attrs | base pointer to a (strided) array specifying attributes of threads to create (may be NULL)
func | a function to execute by each thread
args | base pointer to a (strided) array specifying arguments to func
results | base pointer to a (strided) array to which results of the function call will be stored (may be NULL)
id_stride | the stride of the ids array, in bytes
attr_stride | the stride of the attrs array, in bytes
arg_stride | the stride of the args array, in bytes
result_stride | the stride of the results array, in bytes
long nthreads | number of threads to execute f

in its simplest form,

myth_create_join_many_ex(0, 0, f, X, 0, 0, 0, s, 0, n);

will execute f(args), f(args+s), f(args+2*s), ..., and f(args+(n-1)*s), each by a separate thread and discard their return values. if you want to get return values, give results and result_stride. e.g.,

myth_create_join_many_ex(0, 0, f, X, Y, 0, 0, xs, t, n);

#### is equivalent to

for all i = 0, ..., n | 1 ((void **)(Y + i * t))[0] = f(args + i * s);

note that all stride arguments must be given in bytes. this is to allow you to receive results in a field of an enclosing structure. e.g.,

struct { char stuff[100]; void * result } args[nthreads];

in this case you want to call this function with results = &args[0].result and result_stride = sizeof(args[0]);

consistent with this policy, results is a void pointer, although it is internally used as (void **).

You can similarly specify addresses of attributes and thread ids, using the base pointer and the stride.

#### Returns

0 if succeed.

#### Bug

Should any error occur, it terminates the program rather than returning an error code.

#### See Also

myth_create, myth_join, <myth_thread_attr>

### myth_create_join_various_ex

> int myth_create_join_various_ex( | myth_thread_t | * | ids,
> | myth_thread_attr_t | * | attrs,
> | myth_func_t | * | funcs,
> | void | * | args,
> | void | * | results,
> | size_t |  | id_stride,
> | size_t |  | attr_stride,
> | size_t |  | func_stride,
> | size_t |  | arg_stride,
> | size_t |  | result_stride,
> | long |  | nthreads | )

Create many user-level threads executing various functions with various arguments and attributes and wait for them to complete. This is almost the same with myth_create_join_many_ex, except that you can have threads execute different functions.

#### Parameters

ids | base pointer to a (strided) array, to which thread ids of the created threads wll be stored (may be NULL)
attrs | base pointer to a (strided) array specifying attributes of threads to create (may be NULL)
funcs | base pointer to a (strided) array specifying functions to execute
args | base pointer to a (strided) array specifying arguments to func
results | base pointer to a (strided) array to which results of the function call will be stored (may be NULL)
id_stride | the stride of the ids array, in bytes
attr_stride | the stride of the attrs array, in bytes
func_stride | the stride of the funcs array, in bytes
arg_stride | the stride of the args array, in bytes
result_stride | the stride of the results array, in bytes
long nthreads | number of threads to execute f

in its simplest form,

myth_create_join_many_ex(0, 0, F, X, 0, 0, 0, fs, xs, 0, n);

will execute f_0(args), f_1(args+xs), f_2(args+2*xs), ..., where f_i = *((myth_func_t *)(F + fs * i)), each by a separate thread and discard their return values. if you want to get return values, give results and result_stride. e.g.,

myth_create_join_many_ex(0, 0, f, X, Y, 0, 0, s, t, n);

#### is equivalent to

for all i = 0, ..., n | 1 ((void **)(Y + i * t))[0] = f(args + i * s);

note that all stride arguments must be given in bytes. this is to allow you to receive results in a field of an enclosing structure. e.g.,

struct { char stuff[100]; void * result } args[nthreads];

in this case you want to call this function with results = &args[0].result and result_stride = sizeof(args[0]);

consistent with this policy, results is a void pointer, although it is internally used as (void **).

You can similarly specify addresses of attributes and thread ids, using the base pointer and the stride.

#### Returns

0 if succeed.

#### Bug

Should any error occur, it terminates the program rather than returning an error code.

#### See Also

myth_create, myth_join, <myth_thread_attr>

### myth_detach

> int myth_detach( | myth_thread_t | th | )

### myth_is_myth_worker

> int myth_is_myth_worker( | void | )

#### Returns

1 if the calling OS-level thread is a massivethreads worker. useful when you mix pthreads and massivethreads.

### myth_self

> myth_thread_t myth_self( | void | )

#### Returns

The identifier of the calling thread.

#### See Also

myth_get_worker_num, myth_get_num_workers

### myth_equal

> int myth_equal( | myth_thread_t | t1,
> | myth_thread_t | t2 | )

### myth_thread_attr_init

> int myth_thread_attr_init( | myth_thread_attr_t | * | attr | )

### myth_thread_attr_getdetachstate

> int myth_thread_attr_getdetachstate( | const | myth_thread_attr_t | * | attr,
> |  | int | * | detachstate | )

### myth_thread_attr_setdetachstate

> int myth_thread_attr_setdetachstate( | myth_thread_attr_t | * | attr,
> | int |  | detachstate | )

### myth_thread_attr_getguardsize

> int myth_thread_attr_getguardsize( | const | myth_thread_attr_t | * | attr,
> |  | size_t | * | guardsize | )

### myth_thread_attr_setguardsize

> int myth_thread_attr_setguardsize( | myth_thread_attr_t | * | attr,
> | size_t |  | guardsize | )

### myth_thread_attr_getstacksize

> int myth_thread_attr_getstacksize( | const | myth_thread_attr_t | * | attr,
> |  | size_t | * | stacksize | )

### myth_thread_attr_setstacksize

> int myth_thread_attr_setstacksize( | myth_thread_attr_t | * | attr,
> | size_t |  | stacksize | )

### myth_thread_attr_getstack

> int myth_thread_attr_getstack( | const | myth_thread_attr_t | * | attr,
> |  | void | ** | stackaddr,
> |  | size_t | * | stacksize | )

### myth_thread_attr_setstack

> int myth_thread_attr_setstack( | myth_thread_attr_t | * | attr,
> | void | * | stackaddr,
> | size_t |  | stacksize | )

### myth_getattr_default_np

> int myth_getattr_default_np( | myth_thread_attr_t | * | attr | )

### myth_getattr_np

> int myth_getattr_np( | myth_thread_t |  | thread,
> | myth_thread_attr_t | * | attr | )

### myth_getconcurrency

> int myth_getconcurrency( | void | )

### myth_yield_ex

> void myth_yield_ex( | int | yield_opt | )

Yield execution to another user-level thread.

#### Parameters

yield_opt | take one of the following values and change the behavior.

myth_yield_option_half_half : behave like myth_yield_option_local_first with probability 1/2 and like myth_yield_option_steal_first with probability 1/2 myth_yield_option_local_only : try to yield to another thread in the local run queue. if none exist, the caller keeps running. myth_yield_option_local_first : try to yield to another thread in the local run queue. if none exist, an attempt is made to steal another thread in a remote run queue; if it succeeds, yields to it. otherwise keep running. myth_yield_option_steal_only : an attempt is made to steal another thread in a remote run queue; if it succeeds, yield to it. otherwise keep running. myth_yield_option_steal_first : an attempt is made to steal another thread in a remote run queue; if it succeeds, yield to it. otherwise try to yield to another thread in the local run queue. if none exist, the caller keeps running.

#### Note

Available options as well as detailed behaviors may change in future.

#### See Also

myth_yield

### myth_yield

> void myth_yield( | void | )

it is equivalent to myth_yield_ex(myth_yield_option_half_half); with probability 1/2, try to yield to a thread in the local queue and if none is found try to steal a thread from a remote queue. do the opposite with probability 1/2.

#### See Also

myth_yield

#### Note

The above describes the current implementation, which may change in future. You should not rely on its exact behavior (other than it switches to another user-level thread).

### myth_setcancelstate

> int myth_setcancelstate( | int |  | state,
> | int | * | oldstate | )

### myth_setcanceltype

> int myth_setcanceltype( | int |  | type,
> | int | * | oldtype | )

### myth_cancel

> int myth_cancel( | myth_thread_t | th | )

### myth_testcancel

> void myth_testcancel( | void | )

### Types

### myth_once_t

### Functions

### myth_once

> int myth_once( | myth_once_t | * | once_control,
> | void |  | (*init_routine)(void) | )

### myth_mutex_init

> int myth_mutex_init( |  | myth_mutex_t | * | mutex,
> | const | myth_mutexattr_t | * | attr | )

Initialize a mutex.

#### Parameters

mutex | a pointer to a mutex data structure to initialize.
attr | a pointer to mutex attributes.

#### Returns

zero if suceeds or an errno.

#### See Also

myth_mutex_destroy, myth_mutex_lock, myth_mutex_trylock, myth_mutex_unlock

### myth_mutex_destroy

> int myth_mutex_destroy( | myth_mutex_t | * | mutex | )

Destroy a mutex.

#### Parameters

mutex | a pointer to a mutex data structure to initialize.

#### Returns

zero if suceeds or an errno.

#### See Also

myth_mutex_init, myth_mutex_lock, myth_mutex_trylock, myth_mutex_unlock

### myth_mutex_trylock

> int myth_mutex_trylock( | myth_mutex_t | * | mtx | )

Try to lock a mutex.

#### Parameters

mutex | a mutex to try to lock.

#### Returns

zero if it successfully acquired a lock. an errno otherwise.

#### See Also

myth_mutex_init, myth_mutex_destroy, myth_mutex_lock, myth_mutex_unlock

### myth_mutex_lock

> int myth_mutex_lock( | myth_mutex_t | * | mtx | )

Lock a mutex.

#### Parameters

mutex | a mutex to lock.

#### Returns

zero if suceeds or an errno when an error occurred.

#### See Also

myth_mutex_init, myth_mutex_destroy, myth_mutex_trylock, myth_mutex_unlock

### myth_mutex_timedlock

> int myth_mutex_timedlock( |  | myth_mutex_t | * | mtx,
> | const struct | timespec | * | abstime | )

Lock a mutex.

#### Parameters

mutex | a mutex to lock.
abstime | absolute time the function returns when the lock cannot be acquired

#### Returns

zero if suceeds or an errno when an error occurred.

#### See Also

myth_mutex_init, myth_mutex_destroy, myth_mutex_trylock, myth_mutex_unlock

### myth_mutex_unlock

> int myth_mutex_unlock( | myth_mutex_t | * | mtx | )

Unlock a mutex.

#### Parameters

mutex | a mutex to unlock.

#### Returns

zero if suceeds or an errno when an error occurred.

#### See Also

myth_mutex_init, myth_mutex_destroy, myth_mutex_lock, myth_mutex_trylock

### myth_mutexattr_init

> int myth_mutexattr_init( | myth_mutexattr_t | * | attr | )

### myth_mutexattr_destroy

> int myth_mutexattr_destroy( | myth_mutexattr_t | * | attr | )

### myth_mutexattr_gettype

> int myth_mutexattr_gettype( | const | myth_mutexattr_t | * | attr,
> |  | int | * | type | )

### myth_mutexattr_settype

> int myth_mutexattr_settype( | myth_mutexattr_t | * | attr,
> | int |  | type | )

### myth_rwlock_init

> int myth_rwlock_init( |  | myth_rwlock_t | * | rwlock,
> | const | myth_rwlockattr_t | * | attr | )

### myth_rwlock_destroy

> int myth_rwlock_destroy( | myth_rwlock_t | * | rwlock | )

### myth_rwlock_rdlock

> int myth_rwlock_rdlock( | myth_rwlock_t | * | rwlock | )

### myth_rwlock_tryrdlock

> int myth_rwlock_tryrdlock( | myth_rwlock_t | * | rwlock | )

### myth_rwlock_timedrdlock

> int myth_rwlock_timedrdlock( |  | myth_rwlock_t | * | rwlock,
> | const struct | timespec | * | abstime | )

### myth_rwlock_wrlock

> int myth_rwlock_wrlock( | myth_rwlock_t | * | rwlock | )

### myth_rwlock_trywrlock

> int myth_rwlock_trywrlock( | myth_rwlock_t | * | rwlock | )

### myth_rwlock_timedwrlock

> int myth_rwlock_timedwrlock( |  | myth_rwlock_t | * | rwlock,
> | const struct | timespec | * | abstime | )

### myth_rwlock_unlock

> int myth_rwlock_unlock( | myth_rwlock_t | * | rwlock | )

### myth_rwlockattr_init

> int myth_rwlockattr_init( | myth_rwlockattr_t | * | attr | )

### myth_rwlockattr_destroy

> int myth_rwlockattr_destroy( | myth_rwlockattr_t | * | attr | )

### myth_rwlockattr_getkind

> int myth_rwlockattr_getkind( | const | myth_rwlockattr_t | * | attr,
> |  | int | * | pref | )

### myth_rwlockattr_setkind

> int myth_rwlockattr_setkind( | myth_rwlockattr_t | * | attr,
> | int |  | pref | )

### myth_cond_init

> int myth_cond_init( |  | myth_cond_t | * | cond,
> | const | myth_condattr_t | * | attr | )

Initialize a condition variable.

#### Parameters

cond | a pointer to a condition variable to initialize
attr | a pointer to condition variable attributes, or NULL

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_cond_destroy, myth_cond_wait, myth_cond_signal, myth_cond_broadcast

### myth_cond_destroy

> int myth_cond_destroy( | myth_cond_t | * | cond | )

Destroy a condition variable.

#### Parameters

cond | a pointer to a condition variable to destroy.

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_cond_init, myth_cond_wait, myth_cond_signal, myth_cond_broadcast

### myth_cond_signal

> int myth_cond_signal( | myth_cond_t | * | c | )

Wake up at least one thread blocking on a condition variable.

#### Parameters

cond | a pointer to a condition variable to signal.

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_cond_init, myth_cond_destroy, myth_cond_wait, myth_cond_broadcast

### myth_cond_broadcast

> int myth_cond_broadcast( | myth_cond_t | * | cond | )

Wake up all threads blocking on a condition variable.

#### Parameters

cond | a pointer to a condition variable from which threads are to wake up.

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_cond_init, myth_cond_destroy, myth_cond_wait, myth_cond_signal

### myth_cond_wait

> int myth_cond_wait( | myth_cond_t | * | cond,
> | myth_mutex_t | * | mutex | )

Atomically unlock a mutex and block on a condition variable.

#### Parameters

cond | a pointer to a condition variable to block on.
mutex | a pointer to a mutex to unlock

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_cond_init, myth_cond_destroy, myth_cond_signal, myth_cond_broadcast

### myth_cond_timedwait

> int myth_cond_timedwait( |  | myth_cond_t | * | cond,
> |  | myth_mutex_t | * | mutex,
> | const struct | timespec | * | abstime | )

### myth_condattr_init

> int myth_condattr_init( | myth_condattr_t | * | attr | )

### myth_condattr_destroy

> int myth_condattr_destroy( | myth_condattr_t | * | attr | )

### myth_barrier_init

> int myth_barrier_init( |  | myth_barrier_t | * | barrier,
> | const | myth_barrierattr_t | * | attr,
> | unsigned | int |  | count | )

Initialize a barrier.

#### Parameters

barrier | a pointer to a barrier data structure to initialize.
attr | a pointer to barrier attributes
count | the number of threads going to synchronize with this barrier

#### Returns

Zero if succeeded. An errno if failed.

### myth_barrier_destroy

> int myth_barrier_destroy( | myth_barrier_t | * | barrier | )

Destroy a barrier.

#### Parameters

barrier | a pointer to a barrier data structure to destroy.

### myth_barrier_wait

> int myth_barrier_wait( | myth_barrier_t | * | barrier | )

Wait on a barrier.

#### Parameters

barrier | a pointer to a barrier data structure on which the calling thread synchronizes

#### Returns

When a barrier succeeds, MYTH_BARRIER_SERIAL_THREAD is returned to a single thread whereas zeros to other threads. When a barrier fails, an errno.

### myth_barrierattr_init

> int myth_barrierattr_init( | myth_barrierattr_t | * | attr | )

### myth_barrierattr_destroy

> int myth_barrierattr_destroy( | myth_barrierattr_t | * | attr | )

### myth_join_counter_init

> int myth_join_counter_init( |  | myth_join_counter_t | * | jc,
> | const | myth_join_counterattr_t | * | attr,
> |  | int |  | val | )

### myth_join_counter_wait

> int myth_join_counter_wait( | myth_join_counter_t | * | jc | )

### myth_join_counter_dec

> int myth_join_counter_dec( | myth_join_counter_t | * | jc | )

### myth_join_counterattr_init

> int myth_join_counterattr_init( | myth_join_counterattr_t | * | attr | )

### myth_join_counterattr_destroy

> int myth_join_counterattr_destroy( | myth_join_counterattr_t | * | attr | )

### myth_felock_init

> int myth_felock_init( |  | myth_felock_t | * | fe,
> | const | myth_felockattr_t | * | attr | )

### myth_felock_destroy

> int myth_felock_destroy( | myth_felock_t | * | fe | )

### myth_felock_lock

> int myth_felock_lock( | myth_felock_t | * | fe | )

### myth_felock_unlock

> int myth_felock_unlock( | myth_felock_t | * | fe | )

### myth_felock_wait_and_lock

> int myth_felock_wait_and_lock( | myth_felock_t | * | fe,
> | int |  | status_to_wait | )

### myth_felock_mark_and_signal

> int myth_felock_mark_and_signal( | myth_felock_t | * | fe,
> | int |  | status_to_signal | )

### myth_felock_status

> int myth_felock_status( | myth_felock_t | * | fe | )

### myth_felockattr_init

> int myth_felockattr_init( | myth_felockattr_t | * | attr | )

### myth_felockattr_destroy

> int myth_felockattr_destroy( | myth_felockattr_t | * | attr | )

### myth_uncond_init

> int myth_uncond_init( | myth_uncond_t | * | uncond | )

initialize an uncondition variable.

#### Parameters

uncond | a pointer to an unconditional variable data structure to initialize

#### Returns

zero if it succeeds and non-zero otherwise

### myth_uncond_destroy

> int myth_uncond_destroy( | myth_uncond_t | * | u | )

destroy an uncondition variable.

#### Parameters

uncond | a pointer to an unconditional variable data structure to destroy

#### Returns

zero if it succeeds and non-zero otherwise

### myth_uncond_wait

> int myth_uncond_wait( | myth_uncond_t | * | uncond | )

block on an uncondition variable, to be waken up later by myth_uncond_signal. there can be only one thread blocking on a single myth_uncond_t variable at the same time.

this function is typically called after the caller checked a data structure and learned that it cannot proceed (e.g., a caller thread trying to get an element from a queue learned the queue is empty). unlike cond_wait, however, it does not take an extra mutex variable that is assumed to be held by the caller. thus, it is the user’s responsibility to implement a means to resolve the race condition between the caller (P) and another thread (Q) that might be changing the data structure concurrently. unless correctly done, it might cause a deadlock bug; if Q changes the data structure a moment after P learned it cannot proceed but before P enters myth_uncond_wait, Q might miss the opportunity to wake up P. myth_uncond_signal waits until a thread blocks on myth_uncond_t and wakes it up.

In summary, a typical (correct) sequence to use myth_uncond_wait and myth_uncond_signal is as follows.

#### P

1: atomically_change_data_to_indicate_I_am_sleeping;

2: myth_uncond_wait(u);

#### Q

3: atomically_change_data_to_indicate_none_is_sleeping;

4: myth_uncond_signal(u);

line 1 and 3 must be done atomically with respect to each other. when 1 succeds, a subsequent execution of line 3 by Q must witness P should be blocking. when Q enters line 4, P might not have executed line 2. myth_uncond_signal guarantees it waits for P to enter.

#### Parameters

uncond | a pointer to an unconditional variable data structure on which the calling thread blocks.

#### Returns

zero if it succeeds and non-zero otherwise

### myth_uncond_signal

> int myth_uncond_signal( | myth_uncond_t | * | uncond | )

unblock the thread blocking on uncond. even if no threads are found on uncond at the moment of the call to this function, the caller waits for a thread to block on it, and then wakes it up. in other words, this function always wakes up a thread.

this function is typically called after the caller checked a data structure and learned that a thread should be blocked waiting for a condition to be met. unlike cond_signal, this function does not assume there is a common mutex protecting the data structure. therefore it is the user’s responsibility to implement a means for the caller to be able to “learn that a thread should be blocked.”

see the description of myth_uncond_wait for details.

#### Parameters

uncond | a pointer to an unconditional variable data structure on which a thread is blocked.

#### Returns

zero if it succeeds and non-zero otherwise

### myth_key_create

> int myth_key_create( | myth_key_t | * | key,
> | void |  | (*destr_function)(void *) | )

Create a key for user-level thread-specific data.

#### Parameters

key | a pointer to which the created key will be stored.
destr_function | a pointer to a destructor function.

#### Returns

Zero if succeed, or an errno when an error occurred.

#### Bug

destr_function is ignored in the current implementation.

#### See Also

myth_key_delete, myth_setspecific, myth_getspecific

### myth_key_delete

> int myth_key_delete( | myth_key_t | key | )

Delete a key for user-level thread-specific data.

#### Parameters

key | key to delete

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_key_create, myth_setspecific, myth_getspecific

### myth_setspecific

> int myth_setspecific( |  | myth_key_t |  | key,
> | const | void | * | data | )

Associate a thread-specific data with a key.

#### Parameters

key | a key created by myth_key_create
data | a data to be associated with key

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_key_create, myth_key_delete, myth_getspecific

### myth_getspecific

> void *myth_getspecific( | myth_key_t | key | )

Obtain a user-level thread-specific data associated with a key.

#### Parameters

key | a key to retrieve data.

#### Returns

a data previously associated with key via myth_setspecific, or NULL if no data has been associated with it.

#### See Also

myth_key_create, myth_key_delete, myth_setspecific

### myth_get_worker_num

> int myth_get_worker_num( | void | )

#### Returns

The index of the calling thread, an integer x satisfying 0 <= x < myth_get_num_workers().

#### See Also

myth_get_num_workers

### myth_get_num_workers

> int myth_get_num_workers( | void | )

#### Returns

The number of underlying workers.

#### See Also

myth_get_worker_num

### myth_wls_key_create

> int myth_wls_key_create( | myth_wls_key_t | * | key,
> | void |  | (*destr_function)(void *) | )

Create a key for worker-specific data.

#### Parameters

key | a pointer to which the created key will be stored.
destr_function | a pointer to a destructor function.

wls_key is used to create data specific to each underlying worker. you can think of it as a simple wrapper to pthread_key_create.

#### Returns

Zero if succeed, or an errno when an error occurred.

#### Bug

destr_function is ignored in the current implementation.

#### See Also

myth_wls_key_delete, myth_wls_setspecific, myth_wls_getspecific

### myth_wls_key_delete

> int myth_wls_key_delete( | myth_wls_key_t | key | )

Delete a key for worker-specific data.

#### Parameters

key | key to delete

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_wls_key_create, myth_wls_setspecific, myth_wls_getspecific

### myth_wls_setspecific

> int myth_wls_setspecific( |  | myth_wls_key_t |  | key,
> | const | void | * | data | )

Associate a worker-specific data with a key.

#### Parameters

key | a key created by myth_key_create
data | a data to be associated with key

#### Returns

Zero if succeed, or an errno when an error occurred.

#### See Also

myth_wls_key_create, myth_wls_key_delete, myth_wls_getspecific

### myth_wls_getspecific

> void *myth_wls_getspecific( | myth_wls_key_t | key | )

Obtain a worker-specific data associated with a key.

#### Parameters

key | a key to retrieve data.

#### Returns

a data previously associated with key via myth_wls_setspecific, or NULL if no data has been associated with it.

#### See Also

myth_wls_key_create, myth_wls_key_delete, myth_wls_setspecific

### myth_sched_yield

> int myth_sched_yield( | void | )

### myth_sleep

> unsigned int myth_sleep( | unsigned | int | s | )

### myth_usleep

> int myth_usleep( | useconds_t | usec | )

### myth_nanosleep

> int myth_nanosleep( | const struct | timespec | * | req,
> | struct | timespec | * | rem | )

> int myth_init( | void | )

Initialize MassiveThreads library with default parameters (see myth_init_ex).

> int myth_init_ex( | myth_globalattr_t | * | attr | )

Initialize MassiveThreads library with the specified global attributes.

> void myth_fini( | void | )

Finalize MassiveThreads.

> int myth_globalattr_init( | myth_globalattr_t | * | attr | )

> int myth_globalattr_destroy( | myth_globalattr_t | * | attr | )

> int myth_globalattr_get_stacksize( | myth_globalattr_t | * | attr,
> | size_t | * | stacksize | )

> int myth_globalattr_set_stacksize( | myth_globalattr_t | * | attr,
> | size_t |  | stacksize | )

> int myth_globalattr_get_n_workers( | myth_globalattr_t | * | attr,
> | size_t | * | n_workers | )

> int myth_globalattr_set_n_workers( | myth_globalattr_t | * | attr,
> | size_t |  | n_workers | )

> int myth_globalattr_get_bind_workers( | myth_globalattr_t | * | attr,
> | int | * | bind_workers | )

> int myth_globalattr_set_bind_workers( | myth_globalattr_t | * | attr,
> | int |  | bind_workers | )

> myth_thread_t myth_create( | myth_func_t |  | func,
> | void | * | arg | )

Create a new user-level thread executing func(arg) with default options.

> int myth_create_ex( | myth_thread_t | * | id,
> | myth_thread_attr_t | * | attr,
> | myth_func_t |  | func,
> | void | * | arg | )

Create a new user-level thread executing func(arg) with specified options.

> void myth_exit( | void | * | ret | )

Terminate the calling user-level thread.

> int myth_join( | myth_thread_t |  | th,
> | void | ** | result | )

Wait for the specified thread th to finish.

> int myth_create_join_many_ex( | myth_thread_t | * | ids,
> | myth_thread_attr_t | * | attrs,
> | myth_func_t |  | func,
> | void | * | args,
> | void | * | results,
> | size_t |  | id_stride,
> | size_t |  | attr_stride,
> | size_t |  | arg_stride,
> | size_t |  | result_stride,
> | long |  | nthreads | )

Create many user-level threads executing the same function with various arguments and attributes and wait for them to complete.

> int myth_create_join_various_ex( | myth_thread_t | * | ids,
> | myth_thread_attr_t | * | attrs,
> | myth_func_t | * | funcs,
> | void | * | args,
> | void | * | results,
> | size_t |  | id_stride,
> | size_t |  | attr_stride,
> | size_t |  | func_stride,
> | size_t |  | arg_stride,
> | size_t |  | result_stride,
> | long |  | nthreads | )

Create many user-level threads executing various functions with various arguments and attributes and wait for them to complete.

> int myth_detach( | myth_thread_t | th | )

> int myth_is_myth_worker( | void | )

1 if the calling OS-level thread is a massivethreads worker.

> myth_thread_t myth_self( | void | )

The identifier of the calling thread.

> int myth_equal( | myth_thread_t | t1,
> | myth_thread_t | t2 | )

> int myth_thread_attr_init( | myth_thread_attr_t | * | attr | )

> int myth_thread_attr_getdetachstate( | const | myth_thread_attr_t | * | attr,
> |  | int | * | detachstate | )

> int myth_thread_attr_setdetachstate( | myth_thread_attr_t | * | attr,
> | int |  | detachstate | )

> int myth_thread_attr_getguardsize( | const | myth_thread_attr_t | * | attr,
> |  | size_t | * | guardsize | )

> int myth_thread_attr_setguardsize( | myth_thread_attr_t | * | attr,
> | size_t |  | guardsize | )

> int myth_thread_attr_getstacksize( | const | myth_thread_attr_t | * | attr,
> |  | size_t | * | stacksize | )

> int myth_thread_attr_setstacksize( | myth_thread_attr_t | * | attr,
> | size_t |  | stacksize | )

> int myth_thread_attr_getstack( | const | myth_thread_attr_t | * | attr,
> |  | void | ** | stackaddr,
> |  | size_t | * | stacksize | )

> int myth_thread_attr_setstack( | myth_thread_attr_t | * | attr,
> | void | * | stackaddr,
> | size_t |  | stacksize | )

> int myth_getattr_default_np( | myth_thread_attr_t | * | attr | )

> int myth_getattr_np( | myth_thread_t |  | thread,
> | myth_thread_attr_t | * | attr | )

> int myth_getconcurrency( | void | )

> void myth_yield_ex( | int | yield_opt | )

Yield execution to another user-level thread.

> void myth_yield( | void | )

it is equivalent to myth_yield_ex(myth_yield_option_half_half); with probability 1/2, try to yield to a thread in the local queue and if none is found try to steal a thread from a remote queue.

> int myth_setcancelstate( | int |  | state,
> | int | * | oldstate | )

> int myth_setcanceltype( | int |  | type,
> | int | * | oldtype | )

> int myth_cancel( | myth_thread_t | th | )

> void myth_testcancel( | void | )

> int myth_once( | myth_once_t | * | once_control,
> | void |  | (*init_routine)(void) | )

> int myth_mutex_init( |  | myth_mutex_t | * | mutex,
> | const | myth_mutexattr_t | * | attr | )

Initialize a mutex.

> int myth_mutex_destroy( | myth_mutex_t | * | mutex | )

Destroy a mutex.

> int myth_mutex_trylock( | myth_mutex_t | * | mtx | )

Try to lock a mutex.

> int myth_mutex_lock( | myth_mutex_t | * | mtx | )

Lock a mutex.

> int myth_mutex_timedlock( |  | myth_mutex_t | * | mtx,
> | const struct | timespec | * | abstime | )

Lock a mutex.

> int myth_mutex_unlock( | myth_mutex_t | * | mtx | )

Unlock a mutex.

> int myth_mutexattr_init( | myth_mutexattr_t | * | attr | )

> int myth_mutexattr_destroy( | myth_mutexattr_t | * | attr | )

> int myth_mutexattr_gettype( | const | myth_mutexattr_t | * | attr,
> |  | int | * | type | )

> int myth_mutexattr_settype( | myth_mutexattr_t | * | attr,
> | int |  | type | )

> int myth_rwlock_init( |  | myth_rwlock_t | * | rwlock,
> | const | myth_rwlockattr_t | * | attr | )

> int myth_rwlock_destroy( | myth_rwlock_t | * | rwlock | )

> int myth_rwlock_rdlock( | myth_rwlock_t | * | rwlock | )

> int myth_rwlock_tryrdlock( | myth_rwlock_t | * | rwlock | )

> int myth_rwlock_timedrdlock( |  | myth_rwlock_t | * | rwlock,
> | const struct | timespec | * | abstime | )

> int myth_rwlock_wrlock( | myth_rwlock_t | * | rwlock | )

> int myth_rwlock_trywrlock( | myth_rwlock_t | * | rwlock | )

> int myth_rwlock_timedwrlock( |  | myth_rwlock_t | * | rwlock,
> | const struct | timespec | * | abstime | )

> int myth_rwlock_unlock( | myth_rwlock_t | * | rwlock | )

> int myth_rwlockattr_init( | myth_rwlockattr_t | * | attr | )

> int myth_rwlockattr_destroy( | myth_rwlockattr_t | * | attr | )

> int myth_rwlockattr_getkind( | const | myth_rwlockattr_t | * | attr,
> |  | int | * | pref | )

> int myth_rwlockattr_setkind( | myth_rwlockattr_t | * | attr,
> | int |  | pref | )

> int myth_cond_init( |  | myth_cond_t | * | cond,
> | const | myth_condattr_t | * | attr | )

Initialize a condition variable.

> int myth_cond_destroy( | myth_cond_t | * | cond | )

Destroy a condition variable.

> int myth_cond_signal( | myth_cond_t | * | c | )

Wake up at least one thread blocking on a condition variable.

> int myth_cond_broadcast( | myth_cond_t | * | cond | )

Wake up all threads blocking on a condition variable.

> int myth_cond_wait( | myth_cond_t | * | cond,
> | myth_mutex_t | * | mutex | )

Atomically unlock a mutex and block on a condition variable.

> int myth_cond_timedwait( |  | myth_cond_t | * | cond,
> |  | myth_mutex_t | * | mutex,
> | const struct | timespec | * | abstime | )

> int myth_condattr_init( | myth_condattr_t | * | attr | )

> int myth_condattr_destroy( | myth_condattr_t | * | attr | )

> int myth_barrier_init( |  | myth_barrier_t | * | barrier,
> | const | myth_barrierattr_t | * | attr,
> | unsigned | int |  | count | )

Initialize a barrier.

> int myth_barrier_destroy( | myth_barrier_t | * | barrier | )

Destroy a barrier.

> int myth_barrier_wait( | myth_barrier_t | * | barrier | )

Wait on a barrier.

> int myth_barrierattr_init( | myth_barrierattr_t | * | attr | )

> int myth_barrierattr_destroy( | myth_barrierattr_t | * | attr | )

> int myth_join_counter_init( |  | myth_join_counter_t | * | jc,
> | const | myth_join_counterattr_t | * | attr,
> |  | int |  | val | )

> int myth_join_counter_wait( | myth_join_counter_t | * | jc | )

> int myth_join_counter_dec( | myth_join_counter_t | * | jc | )

> int myth_join_counterattr_init( | myth_join_counterattr_t | * | attr | )

> int myth_join_counterattr_destroy( | myth_join_counterattr_t | * | attr | )

> int myth_felock_init( |  | myth_felock_t | * | fe,
> | const | myth_felockattr_t | * | attr | )

> int myth_felock_destroy( | myth_felock_t | * | fe | )

> int myth_felock_lock( | myth_felock_t | * | fe | )

> int myth_felock_unlock( | myth_felock_t | * | fe | )

> int myth_felock_wait_and_lock( | myth_felock_t | * | fe,
> | int |  | status_to_wait | )

> int myth_felock_mark_and_signal( | myth_felock_t | * | fe,
> | int |  | status_to_signal | )

> int myth_felock_status( | myth_felock_t | * | fe | )

> int myth_felockattr_init( | myth_felockattr_t | * | attr | )

> int myth_felockattr_destroy( | myth_felockattr_t | * | attr | )

> int myth_uncond_init( | myth_uncond_t | * | uncond | )

initialize an uncondition variable.

> int myth_uncond_destroy( | myth_uncond_t | * | u | )

destroy an uncondition variable.

> int myth_uncond_wait( | myth_uncond_t | * | uncond | )

block on an uncondition variable, to be waken up later by myth_uncond_signal.

> int myth_uncond_signal( | myth_uncond_t | * | uncond | )

unblock the thread blocking on uncond.

> int myth_key_create( | myth_key_t | * | key,
> | void |  | (*destr_function)(void *) | )

Create a key for user-level thread-specific data.

> int myth_key_delete( | myth_key_t | key | )

Delete a key for user-level thread-specific data.

> int myth_setspecific( |  | myth_key_t |  | key,
> | const | void | * | data | )

Associate a thread-specific data with a key.

> void *myth_getspecific( | myth_key_t | key | )

Obtain a user-level thread-specific data associated with a key.

> int myth_get_worker_num( | void | )

The index of the calling thread, an integer x satisfying 0 <= x < myth_get_num_workers().

> int myth_get_num_workers( | void | )

The number of underlying workers.

> int myth_wls_key_create( | myth_wls_key_t | * | key,
> | void |  | (*destr_function)(void *) | )

Create a key for worker-specific data.

> int myth_wls_key_delete( | myth_wls_key_t | key | )

Delete a key for worker-specific data.

> int myth_wls_setspecific( |  | myth_wls_key_t |  | key,
> | const | void | * | data | )

Associate a worker-specific data with a key.

> void *myth_wls_getspecific( | myth_wls_key_t | key | )

Obtain a worker-specific data associated with a key.

> int myth_sched_yield( | void | )

> unsigned int myth_sleep( | unsigned | int | s | )

> int myth_usleep( | useconds_t | usec | )

> int myth_nanosleep( | const struct | timespec | * | req,
> | struct | timespec | * | rem | )

Close