Lthread¶

lthread_create¶

int thread_create(lthread_t **new_lt, lthread_func func, void *arg)¶

Creates a new lthread.

Parameters:	new_lt (lthread_t) – a ptr->ptr to store the new lthread structure on success func** (lthread_func) – Function to run in an lthread. arg (void*) – Argument to pass to func when called.
Returns:	0 on success with new_lt pointing to the new lthread.
Returns:	-1 on failure with errno specifying the reason.

lthread_func: void (*)(void*)¶

lthread_sleep¶

void lthread_sleep(uint64_t msecs)¶

Causes an lthread to sleep for msecs milliseconds.

Parameters:	msecs (uint64_t) – Number of milliseconds to sleep. msecs=0 causes the lthread to yield and allow other lthreads to resume before it continues.

lthread_cancel¶

void lthread_cancel(lthread_t *lt)¶

Cancels lthread and prepares it to be removed from lthread scheduler. If it was waiting for events, the events will get cancelled. If an lthread was joining on it, the lthread joining will get scheduled to run.

Parameters:	lt (lthread_t*) – lthread to cancel

lthread_run¶

void lthread_run(void)¶: Runs lthread scheduler until all lthreads return.

lthread_join¶

int lthread_join(lthread_t *lt, void **ptr, uint64_t timeout)¶

Blocks the calling lthread until lt has exited or a timeout occurred. In case of timeout, lthread_join returns -2 and lt doesn’t get freed. If target lthread was cancelled, it returns -1 and the target lthread will be freed. **ptr will get populated by lthread_exit(). ptr cannot be from lthread’s stack space. Joining on a joined lthread has undefined behavior.

Parameters:	lt (lthread_t) – lthread to join on. ptr* (void) – optional, this ptr will be populated by `lthread_exit()`. timeout** (uint64_t) – How long to wait trying to join on lt before timing out.
Returns:	0 on success.
Returns:	-1 if target lthread got cancelled.
Returns:	-2 on timeout.

Attention

Joining on a joined lthread has undefined behavior

lthread_detach¶

void lthread_detach(void)¶: Marks the current lthread as detached, causing it to get freed once it exits. Otherwise lthread_join() must be called on the lthread to free it up. If an lthread wasn’t marked as detached and wasn’t joined on then a memory leak occurs.

lthread_detach2¶

void lthread_detach2(lthread_t *lt)¶

Same as lthread_detach() except that it doesn’t have to be called from within the lthread function. The lthread to detach is passed as a param.

Parameters:	lt (lthread_t*) – Lthread to detach.

lthread_exit¶

void lthread_exit(void *ptr)¶

Sets ptr value for the lthread calling lthread_join() and exits lthread.

Parameters:	ptr (void*) – Optional, ptr value to pass to the joining lthread.

lthread_wakeup¶

void lthread_wakeup(lthread_t *lt)¶

Wakes up a sleeping lthread. If lthread wasn’t sleeping this function has no effect.

Parameters:	lt (lthread_t*) – The lthread to wake up.

lthread_cond_create¶

int lthread_cond_create(lthread_cond_t **c)¶

Creates a condition variable that can be used between lthreads to block/signal each other.

Parameters:	c (lthread_cond_t**) – ptr->ptr that will be populated on success.
Returns:	0 on success.
Returns:	-1 on error with errno containing the reason.

lthread_cond_wait¶

int lthread_cond_wait(lthread_cond_t *c, uint64_t timeout)¶

Puts the lthread calling lthread_cond_wait() to sleep until timeout expires or another lthread signals it.

Parameters:	c (lthread_cond_t) – condition variable created by `lthread_cond_create()` and shared between lthreads requiring synchronization. timeout* (uint64_t) – Number of milliseconds to wait on the condition variable to be signaled before it times out. 0 to wait indefinitely.
Returns:	0 if it was signal.
Returns:	-2 on timeout.

lthread_cond_signal¶

void lthread_cond_signal(lthread_cond_t *c)¶

Signals a single lthread blocked on lthread_cond_wait() to wake up and resume.

Parameters:	c (lthread_cond_t*) – condition variable created by `lthread_cond_create()` and shared between lthreads requiring synchronization.

lthread_cond_broadcast¶

void lthread_cond_broadcast(lthread_cond_t *c)¶

Signals all lthreads blocked on lthread_cond_wait() to wake up and resume.

Parameters:	c (lthread_cond_t*) – condition variable created by `lthread_cond_create()` and shared between lthreads requiring synchronization.

lthread_set_data¶

void lthread_set_data(void *data)¶

Sets data bound to the lthread. This value can be retrieved anywhere in the lthread using lthread_get_data().

Parameters:	data (void*) – value to be set.

lthread_get_data¶

void *lthread_get_data(void)¶

Returns the value set for the current lthread.

Returns:	Value set by `lthread_set_data()`

lthread_current¶

lthread_t *lthread_current()¶

Returns a pointer to the current lthread.

Returns:	ptr to the current lthread running.

lthread_compute_begin¶

int lthread_compute_begin(void)¶

Resumes lthread inside a pthread to run expensive computations or make a blocking call like gethostbyname(). This call must be followed by lthread_compute_end() after the computation and/or blocking calls statements have been made, to resume the lthread in its original lthread scheduler. No lthread_* calls can be made during the 2 calls.

Returns:	0 on success.
Returns:	-1 if lthread failed to resume it in a pthread.

lthread_compute_end¶

void lthread_compute_end(void)¶: Moves lthread from pthread back to the lthread scheduler it was running on.

DEFINE_LTHREAD¶

DEFINE_LTHREAD(name)¶: Sets the name of the function inside the lthread structure for easier crash debugging. Must be called inside the lthread.