Struct sgx_tstd::sync::SgxThreadCondvar

pub struct SgxThreadCondvar { /* fields omitted */ }

The structure of sgx condition.

Methods

impl SgxThreadCondvar

pub const fn new() -> Self

The function initializes a trusted condition variable within the enclave.

Description

When a thread creates a condition variable within an enclave, it simply initializes the various fields of the object to indicate that the condition variable is available. The results of using a condition variable in a wait, signal or broadcast operation before it has been fully initialized are undefined. To avoid race conditions in the initialization of a condition variable, it is recommended statically initializing the condition variable with the macro SGX_THREAD_COND_INITIALIZER.

Requirements

Library: libsgx_tstdc.a

pub unsafe fn wait(&self, mutex: &SgxThreadMutex) -> SysError

The function waits on a condition variable within an enclave.

Description

A condition variable is always used in conjunction with a mutex. To wait on a condition variable, a thread first needs to acquire the condition variable spin lock. After the spin lock is acquired, the thread updates the condition variable waiting queue. To avoid the lost wake-up signal problem, the condition variable spin lock is released after the mutex. This order ensures the function atomically releases the mutex and causes the calling thread to block on the condition variable, with respect to other threads accessing the mutex and the condition variable. After releasing the condition variable spin lock, the thread makes an OCALL to get suspended. When the thread is awakened, it acquires the condition variable spin lock. The thread then searches the condition variable queue. If the thread is in the queue, it means that the thread was already waiting on the condition variable outside the enclave, and it has been awakened unexpectedly. When this happens, the thread releases the condition variable spin lock, makes an OCALL and simply goes back to sleep. Otherwise, another thread has signaled or broadcasted the condition variable and this thread may proceed. Before returning, the thread releases the condition variable spin lock and acquires the mutex, ensuring that upon returning from the function call the thread still owns the mutex.

Requirements

Library: libsgx_tstdc.a

Parameters

mutex

The trusted mutex object that will be unlocked when the thread is blocked inthe condition variable

Errors

EINVAL

The trusted condition variable or mutex object is invalid or the mutex is not locked.

EPERM

The trusted mutex is locked by another thread.

pub unsafe fn signal(&self) -> SysError

The function wakes a pending thread waiting on the condition variable.

Description

To signal a condition variable, a thread starts acquiring the condition variable spin-lock. Then it inspects the status of the condition variable queue. If the queue is empty it means that there are not any threads waiting on the condition variable. When that happens, the thread releases the condition variable and returns. However, if the queue is not empty, the thread removes the first thread waiting in the queue. The thread then makes an OCALL to wake up the thread that is suspended outside the enclave, but first the thread releases the condition variable spin-lock. Upon returning from the OCALL, the thread continues normal execution.

Requirements

Library: libsgx_tstdc.a

Errors

EINVAL

The trusted condition variable is invalid.

pub unsafe fn broadcast(&self) -> SysError

The function wakes all pending threads waiting on the condition variable.

Description

Broadcast and signal operations on a condition variable are analogous. The only difference is that during a broadcast operation, the thread removes all the threads waiting on the condition variable queue and wakes up all the threads suspended outside the enclave in a single OCALL.

Requirements

Library: libsgx_tstdc.a

Errors

EINVAL

The trusted condition variable is invalid.

ENOMEM

Internal memory allocation failed.

pub unsafe fn destroy(&self) -> SysError

The function destroys a trusted condition variable within an enclave.

Description

The procedure first confirms that there are no threads waiting on the condition variable before it is destroyed. The destroy operation acquires the spin lock at the beginning of the operation to prevent other threads from signaling to or waiting on the condition variable.

Requirements

Library: libsgx_tstdc.a

Errors

EINVAL

The trusted condition variable is invalid.

EBUSY

The condition variable has pending threads waiting on it.

pub unsafe fn get_raw(&self) -> &mut sgx_thread_cond_t

Get the pointer of sgx_thread_cond_t in SgxThreadCondvar.

Trait Implementations

impl Send for SgxThreadCondvar

impl Sync for SgxThreadCondvar