Struct sgx_tstd::sync::SgxThreadMutex

pub struct SgxThreadMutex { /* fields omitted */ }

The structure of sgx mutex.

Methods

impl SgxThreadMutex

pub const fn new() -> Self

The function initializes a trusted mutex object within the enclave.

Description

When a thread creates a mutex within an enclave, sgx_thread_mutex_ init simply initializes the various fields of the mutex object to indicate that the mutex is available. rsgx_thread_mutex_init creates a non-recursive mutex. The results of using a mutex in a lock or unlock operation before it has been fully initialized (for example, the function call to rsgx_thread_mutex_ init returns) are undefined. To avoid race conditions in the initialization of a trusted mutex, it is recommended statically initializing the mutex with the macro SGX_THREAD_MUTEX_INITIALIZER, SGX_THREAD_NON_RECURSIVE_MUTEX_INITIALIZER , of, or SGX_THREAD_RECURSIVE_MUTEX_INITIALIZER instead.

Requirements

Library: libsgx_tstdc.a

Return value

The trusted mutex object to be initialized.

pub unsafe fn lock(&self) -> SysError

The function locks a trusted mutex object within an enclave.

Description

To acquire a mutex, a thread first needs to acquire the corresponding spin lock. After the spin lock is acquired, the thread checks whether the mutex is available. If the queue is empty or the thread is at the head of the queue the thread will now become the owner of the mutex. To confirm its ownership, the thread updates the refcount and owner fields. If the mutex is not available, the thread searches the queue. If the thread is already in the queue, but not at the head, it means that the thread has previously tried to lock the mutex, but it did not succeed and had to wait outside the enclave and it has been awakened unexpectedly. When this happens, the thread makes an OCALL and simply goes back to sleep. If the thread is trying to lock the mutex for the first time, it will update the waiting queue and make an OCALL to get suspended. Note that threads release the spin lock after acquiring the mutex or before leaving the enclave.

Note

A thread should not exit an enclave returning from a root ECALL after acquiring the ownership of a mutex. Do not split the critical section protected by a mutex across root ECALLs.

Requirements

Library: libsgx_tstdc.a

Errors

EINVAL

The trusted mutex object is invalid.

pub unsafe fn try_lock(&self) -> SysError

The function tries to lock a trusted mutex object within an enclave.

Description

A thread may check the status of the mutex, which implies acquiring the spin lock and verifying that the mutex is available and that the queue is empty or the thread is at the head of the queue. When this happens, the thread acquires the mutex, releases the spin lock and returns 0. Otherwise, the thread releases the spin lock and returns EINVAL/EBUSY. The thread is not suspended in this case.

Note

A thread should not exit an enclave returning from a root ECALL after acquiring the ownership of a mutex. Do not split the critical section protected by a mutex across root ECALLs.

Requirements

Library: libsgx_tstdc.a

Errors

EINVAL

The trusted mutex object is invalid.

EBUSY

The mutex is locked by another thread or has pending threads to acquire the mutex

pub unsafe fn unlock(&self) -> SysError

The function unlocks a trusted mutex object within an enclave.

Description

Before a thread releases a mutex, it has to verify it is the owner of the mutex. If that is the case, the thread decreases the refcount by 1 and then may either continue normal execution or wakeup the first thread in the queue. Note that to ensure the state of the mutex remains consistent, the thread that is awakened by the thread releasing the mutex will then try to acquire the mutex almost as in the initial call to the rsgx_thread_mutex_lock routine.

Requirements

Library: libsgx_tstdc.a

Errors

EINVAL

The trusted mutex object is invalid or it is not locked by any thread.

EPERM

The mutex is locked by another thread.

pub unsafe fn destroy(&self) -> SysError

The function destroys a trusted mutex object within an enclave.

Description

rsgx_thread_mutex_destroy resets the mutex, which brings it to its initial status. In this process, certain fields are checked to prevent releasing a mutex that is still owned by a thread or on which threads are still waiting.

Note

Locking or unlocking a mutex after it has been destroyed results in undefined behavior. After a mutex is destroyed, it must be re-created before it can be used again.

Requirements

Library: libsgx_tstdc.a

Errors

EINVAL

The trusted mutex object is invalid.

EBUSY

The mutex is locked by another thread or has pending threads to acquire the mutex.

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

Get the pointer of sgx_thread_mutex_t in SgxThreadMutex.

Trait Implementations

impl Send for SgxThreadMutex

impl Sync for SgxThreadMutex