myth.h

Summary
myth.h
Functions
myth_initInitialize MassiveThreads library with default parameters (see myth_init_ex).
myth_init_exInitialize MassiveThreads library with the specified global attributes.
myth_finiFinalize 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_createCreate a new user-level thread executing func(arg) with default options.
myth_create_exCreate a new user-level thread executing func(arg) with specified options.
myth_exitTerminate the calling user-level thread.
myth_joinWait for the specified thread th to finish.
myth_create_join_many_exCreate many user-level threads executing the same function with various arguments and attributes and wait for them to complete.
myth_create_join_various_exCreate many user-level threads executing various functions with various arguments and attributes and wait for them to complete.
myth_detach
myth_is_myth_worker1 if the calling OS-level thread is a massivethreads worker.
myth_selfThe 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_exYield execution to another user-level thread.
myth_yieldit 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_initInitialize a mutex.
myth_mutex_destroyDestroy a mutex.
myth_mutex_trylockTry to lock a mutex.
myth_mutex_lockLock a mutex.
myth_mutex_timedlockLock a mutex.
myth_mutex_unlockUnlock 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_initInitialize a condition variable.
myth_cond_destroyDestroy a condition variable.
myth_cond_signalWake up at least one thread blocking on a condition variable.
myth_cond_broadcastWake up all threads blocking on a condition variable.
myth_cond_waitAtomically unlock a mutex and block on a condition variable.
myth_cond_timedwait
myth_condattr_init
myth_condattr_destroy
myth_barrier_initInitialize a barrier.
myth_barrier_destroyDestroy a barrier.
myth_barrier_waitWait 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_initinitialize an uncondition variable.
myth_uncond_destroydestroy an uncondition variable.
myth_uncond_waitblock on an uncondition variable, to be waken up later by myth_uncond_signal.
myth_uncond_signalunblock the thread blocking on uncond.
myth_key_createCreate a key for user-level thread-specific data.
myth_key_deleteDelete a key for user-level thread-specific data.
myth_setspecificAssociate a thread-specific data with a key.
myth_getspecificObtain a user-level thread-specific data associated with a key.
myth_get_worker_numThe index of the calling thread, an integer x satisfying 0 <= x < myth_get_num_workers().
myth_get_num_workersThe number of underlying workers.
myth_wls_key_createCreate a key for worker-specific data.
myth_wls_key_deleteDelete a key for worker-specific data.
myth_wls_setspecificAssociate a worker-specific data with a key.
myth_wls_getspecificObtain 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

attrthe 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

attrglobal 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

attrglobal 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

attrglobal attribute to get stack size of
stacksizeaddress 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

attrglobal attribute to set stack size of
stacksizethe 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

attrglobal attribute to get the number of workers of
n_workersthe 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

attrglobal attribute to set the number of workers of
n_workersthe 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

attrglobal attribute to get the bind_workers attribute of
bind_workersthe 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

attrglobal attribute to set the bind_workers attribute of
bind_workers1 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

funca pointer to a function.
arga 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

ida pointer, if not NULL, to which id of the created thread will be stored.
funca pointer to a function.
arga pointer given to func.
attra 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

retexit 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

ththe identifier of the thread to wait for
resulta 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

idsbase pointer to a (strided) array, to which thread ids of the created threads wll be stored (may be NULL)
attrsbase pointer to a (strided) array specifying attributes of threads to create (may be NULL)
funca function to execute by each thread
argsbase pointer to a (strided) array specifying arguments to func
resultsbase pointer to a (strided) array to which results of the function call will be stored (may be NULL)
id_stridethe stride of the ids array, in bytes
attr_stridethe stride of the attrs array, in bytes
arg_stridethe stride of the args array, in bytes
result_stridethe stride of the results array, in bytes
long nthreadsnumber 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, ..., n1 ((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

idsbase pointer to a (strided) array, to which thread ids of the created threads wll be stored (may be NULL)
attrsbase pointer to a (strided) array specifying attributes of threads to create (may be NULL)
funcsbase pointer to a (strided) array specifying functions to execute
argsbase pointer to a (strided) array specifying arguments to func
resultsbase pointer to a (strided) array to which results of the function call will be stored (may be NULL)
id_stridethe stride of the ids array, in bytes
attr_stridethe stride of the attrs array, in bytes
func_stridethe stride of the funcs array, in bytes
arg_stridethe stride of the args array, in bytes
result_stridethe stride of the results array, in bytes
long nthreadsnumber 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, ..., n1 ((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_opttake 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

mutexa pointer to a mutex data structure to initialize.
attra 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

mutexa 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

mutexa 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

mutexa 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

mutexa mutex to lock.
abstimeabsolute 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

mutexa 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

conda pointer to a condition variable to initialize
attra 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

conda 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

conda 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

conda 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

conda pointer to a condition variable to block on.
mutexa 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

barriera pointer to a barrier data structure to initialize.
attra pointer to barrier attributes
countthe 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

barriera pointer to a barrier data structure to destroy.

myth_barrier_wait

int myth_barrier_wait(myth_barrier_t *barrier)

Wait on a barrier.

Parameters

barriera 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

unconda 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

unconda 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

unconda 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

unconda 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

keya pointer to which the created key will be stored.
destr_functiona 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

keykey 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

keya key created by myth_key_create
dataa 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

keya 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

keya pointer to which the created key will be stored.
destr_functiona 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

keykey 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

keya key created by myth_key_create
dataa 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

keya 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