Starboard Module Reference: condition_variable.h

Defines an interface for condition variables.

Enums

SbConditionVariableResult

Enumeration of possible results from waiting on a condvar.

Values

  • kSbConditionVariableSignaled - The wait completed because the condition variable was signaled.
  • kSbConditionVariableTimedOut - The wait completed because it timed out, and was not signaled.
  • kSbConditionVariableFailed - The wait failed, either because a parameter wasn't valid, or the conditionvariable has already been destroyed, or something similar.

Functions

SbConditionVariableBroadcast

Description

Broadcasts to all current waiters of condition to stop waiting. This function wakes all of the threads waiting on condition while SbConditionVariableSignal wakes a single thread.

Declaration and definitions

SB_EXPORT bool SbConditionVariableBroadcast(SbConditionVariable* condition);

#include "starboard/condition_variable.h"

bool SbConditionVariableBroadcast(SbConditionVariable* /*condition*/) {
  return false;
}

Parameters

Parameters
SbConditionVariable*
condition
The condition that should no longer be waited for.

SbConditionVariableCreate

Description

Creates a new condition variable to work with opt_mutex, which may be null, placing the newly created condition variable in out_condition.
The return value indicates whether the condition variable could be created.

Declaration and definitions

SB_EXPORT bool SbConditionVariableCreate(SbConditionVariable* out_condition,
                                         SbMutex* opt_mutex);

#include "starboard/condition_variable.h"

bool SbConditionVariableCreate(SbConditionVariable* /*out_condition*/,
                               SbMutex* /*opt_mutex*/) {
  return false;
}

Parameters

Parameters
SbConditionVariable*
out_condition
SbMutex*
opt_mutex

SbConditionVariableDestroy

Description

Destroys the specified SbConditionVariable. The return value indicates whether the destruction was successful. The behavior is undefined if other threads are currently waiting on this condition variable.

Declaration and definitions

SB_EXPORT bool SbConditionVariableDestroy(SbConditionVariable* condition);

#include "starboard/condition_variable.h"

bool SbConditionVariableDestroy(SbConditionVariable* /*condition*/) {
  return false;
}

Parameters

Parameters
SbConditionVariable*
condition
The SbConditionVariable to be destroyed. This invalidates the condition variable.

SbConditionVariableIsSignaled

Description

Returns whether the given result is a success.

Declaration

static SB_C_INLINE bool SbConditionVariableIsSignaled(
    SbConditionVariableResult result) {
  return result == kSbConditionVariableSignaled;
}

Parameters

Parameters
SbConditionVariableResult
result

SbConditionVariableSignal

Description

Signals the next waiter of condition to stop waiting. This function wakes a single thread waiting on condition while SbConditionVariableBroadcast wakes all threads waiting on it.

Declaration and definitions

SB_EXPORT bool SbConditionVariableSignal(SbConditionVariable* condition);

#include "starboard/condition_variable.h"

bool SbConditionVariableSignal(SbConditionVariable* /*condition*/) {
  return false;
}

Parameters

Parameters
SbConditionVariable*
condition
The condition that the waiter should stop waiting for.

SbConditionVariableWait

Description

Waits for condition, releasing the held lock mutex, blocking indefinitely, and returning the result. Behavior is undefined if mutex is not held.

Declaration and definitions

SB_EXPORT SbConditionVariableResult
SbConditionVariableWait(SbConditionVariable* condition, SbMutex* mutex);

#include "starboard/condition_variable.h"

SbConditionVariableResult SbConditionVariableWait(
    SbConditionVariable* /*condition*/,
    SbMutex* /*mutex*/) {
  return kSbConditionVariableFailed;
}

Parameters

Parameters
SbConditionVariable*
condition
SbMutex*
mutex

SbConditionVariableWaitTimed

Description

Waits for condition, releasing the held lock mutex, blocking up to timeout_duration, and returning the acquisition result. Behavior is undefined if mutex is not held.

Declaration and definitions

SB_EXPORT SbConditionVariableResult
SbConditionVariableWaitTimed(SbConditionVariable* condition,
                             SbMutex* mutex,
                             SbTime timeout_duration);

#include "starboard/condition_variable.h"

SbConditionVariableResult SbConditionVariableWaitTimed(
    SbConditionVariable* /*condition*/,
    SbMutex* /*mutex*/,
    SbTime /*timeout*/) {
  return kSbConditionVariableFailed;
}

Parameters

Parameters
SbConditionVariable*
condition
SbMutex*
mutex
SbTime
timeout_duration
The maximum amount of time that function should wait for condition. If the timeout_duration value is less than or equal to zero, the function returns as quickly as possible with a kSbConditionVariableTimedOut result.