futex (Fast Userspace Mutex)

Header: udo/futex.h

Table of contents (click to go)

Macros

1. udo_futex_wait_cond

Enums

Unions

Structs

1. udo_futex_create_info

Functions

1. udo_futex_create()

2. udo_futex_lock()

3. udo_futex_unlock()

4. udo_futex_unlock_force()

5. udo_futex_wake_cond()

6. udo_futex_destroy()

API Documentation

udo_futex_create_info

Structure passed to udo_futex_create() used

to define size of shared memory and amount of

futexes contained at the start of shared memory.

struct udo_futex_create_info

size_t size;

uint32_t count;

size

Size of shared memory block.

count

Amount of futexes stored in a single

shared memory block. The amount of

futexes caller may allocate is limited

to 1024.

udo_futex_create

udo_atomic_u32 *udo_futex_create(const void *futex_info);

Allocates shared memory space that may be used

to store a futex. This function usage should

be limited to processes/threads that were created

via fork() or pthread_create(). For processes

created without fork() (i.e separate application)

see shm.c implementation. By default all futexes

are initialize in the locked state.

Futex Memory Block (3 futexes)

Data Stored	Offset In Bytes	Byte Size	Initial Value
P1 Futex	0	4	1 (locked)
P2 Futex	4	4	1 (locked)
P3 Futex	8	4	1 (locked)

Param	Decription
futex_info	Implementation uses a pointer to a struct udo_futex_create_info.

Returns:

on success: Pointer to a udo_atomic_u32

on failure: NULL

---

udo_futex_lock

void udo_futex_lock(udo_atomic_u32 *fux);

Atomically updates futex value to the locked state.

If value can’t be changed inform kernel that a

process/thread needs to be put to sleep. Sets errno

to EINTR if a call to udo_futex_unlock_force()

is made.

Param	Decription
fux	Pointer to 32-bit unsigned integer storing futex value.

---

udo_futex_wait

void udo_futex_wait(udo_atomic_u32 *fux, const uint32_t desired);

Wait until the futex value is in the desired state.

If value can’t be changed inform kernel that a

process/thread needs to be put to sleep. Sets errno to

EINTR if a call to udo_futex_unlock_force()

is made.

Param	Decription
fux	Pointer to 32-bit unsigned integer storing futex value.
desired	Must pass value to wait on.

---

udo_futex_wait_cond

udo_futex_wait_cond(fux, cond)

Wait until the the conditional expression

is meet. Then inform kernel to wake up all

processes/threads watching the futex. The

value at the futex isn’t required when

using this macro. Sets errno to EINTR if

a call to udo_futex_unlock_force() is made.

NOTE: This macro wraps the function

void p_udo_futex_wait_cond(udo_atomic_u32 *fux).

Param	Decription
fux	Pointer to 32-bit unsigned integer storing futex value.
cond	If statement conditional expression to meet. If condition not meet inform kernel to wake up all processes/threads watching the futex.

---

udo_futex_unlock

void udo_futex_unlock(udo_atomic_u32 *fux);

Atomically update futex value to the unlocked state.

Then inform kernel to wake up all processes/threads

watching the futex.

Param	Decription
fux	Pointer to 32-bit unsigned integer storing futex value.

udo_futex_unlock_force

void udo_futex_unlock_force(udo_atomic_u32 *fux);

Atomically update futex value to the force unlocked state.

Then inform kernel to wake up all processes/threads

watching the futex. When force unlocking if a

process/thread is waiting on the lock. Process/thread

will exit setting errno to EINTR. Recommended to use

function in a signal handler.

Param	Decription
fux	Pointer to 32-bit unsigned integer storing futex value.

---

udo_futex_wake

void udo_futex_wake(udo_atomic_u32 *fux, const uint32_t desired);

Atomically update futex value to the desired state.

Then inform kernel to wake up all processes/threads

watching the futex.

Param	Decription
fux	Pointer to 32-bit unsigned integer storing futex value.
desired	Must pass value to store in futex.

---

udo_futex_wake_cond

void udo_futex_wake_cond(udo_atomic_u32 *fux);

Wakes all processes/threads waiting

on a specific conditional expression

to be meet.

Conditional expressions may be set

with a call to udo_futex_wait_cond.

Param	Decription
fux	Pointer to 32-bit unsigned integer storing futex value.

---

udo_futex_destroy

void udo_futex_destroy(udo_atomic_u32 *fux, const size_t size);

Frees any allocated memory and closes FD’s (if open)

created after udo_futex_create() call.

Param	Decription
fux	Pointer to 32-bit unsigned integer storing futex value.
size	Size of shared memory block.

---