Semaphore Class Reference

The Semaphore class is used to manage and protect access to a set of shared resources. More...

#include <Semaphore.h>

Inheritance diagram for Semaphore:

Public Member Functions
	Semaphore (int32_t count=0)
	Create and Initialize a Semaphore object used for managing resources. More...
	Semaphore (int32_t count, uint16_t max_count)
	Create and Initialize a Semaphore object used for managing resources. More...
void	acquire ()
	Wait until a Semaphore resource becomes available. More...
bool	try_acquire ()
	Try to acquire a Semaphore resource, and return immediately. More...
bool	try_acquire_for (uint32_t millisec)
	Wait until a Semaphore resource becomes available. More...
bool	try_acquire_for (Kernel::Clock::duration_u32 rel_time)
	Wait until a Semaphore resource becomes available. More...
bool	try_acquire_until (uint64_t millisec)
	Wait until a Semaphore resource becomes available. More...
bool	try_acquire_until (Kernel::Clock::time_point abs_time)
	Wait until a Semaphore resource becomes available. More...
osStatus	release (void)
	Release a Semaphore resource that was obtain with Semaphore::acquire. More...
	~Semaphore ()
	Semaphore destructor. More...

Detailed Description

The Semaphore class is used to manage and protect access to a set of shared resources.

Note

Memory considerations: The semaphore control structures will be created on current thread's stack, both for the mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).

Definition at line 50 of file Semaphore.h.

Constructor & Destructor Documentation

Semaphore() [1/2]

Semaphore

(

int32_t

count = 0

)

Create and Initialize a Semaphore object used for managing resources.

Parameters

count

number of available resources; maximum index value is (count-1). (default: 0).

Note

You cannot call this function from ISR context.

Semaphore() [2/2]

Semaphore	(	int32_t	count,
		uint16_t	max_count
	)

Create and Initialize a Semaphore object used for managing resources.

Parameters

count	number of available resources
max_count	maximum number of available resources

Note

You cannot call this function from ISR context.

~Semaphore()

~Semaphore

(

)

Semaphore destructor.

Note

You cannot call this function from ISR context.

Member Function Documentation

acquire()

void acquire

(

)

Wait until a Semaphore resource becomes available.

Note

You cannot call this function from ISR context.

try_acquire()

bool try_acquire

(

)

Try to acquire a Semaphore resource, and return immediately.

Returns

true if a resource was acquired, false otherwise.

Note

equivalent to try_acquire_for(0)

You may call this function from ISR context.

try_acquire_for() [1/2]

bool try_acquire_for

(

uint32_t

millisec

)

Wait until a Semaphore resource becomes available.

Parameters

millisec

timeout value.

Returns

true if a resource was acquired, false otherwise.

Note

You may call this function from ISR context if the millisec parameter is set to 0.

Deprecated:

Pass a chrono duration, not an integer millisecond count. For example use 5s rather than 5000.

try_acquire_for() [2/2]

bool try_acquire_for

(

Kernel::Clock::duration_u32

rel_time

)

Wait until a Semaphore resource becomes available.

Parameters

rel_time

timeout value.

Returns

true if a resource was acquired, false otherwise.

Note

You may call this function from ISR context if the rel_time parameter is set to 0.

try_acquire_until() [1/2]

bool try_acquire_until

(

uint64_t

millisec

)

Wait until a Semaphore resource becomes available.

Parameters

millisec

absolute timeout time, referenced to Kernel::get_ms_count()

Returns

true if a resource was acquired, false otherwise.

Note

the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the acquire attempt will time out earlier than specified.

You cannot call this function from ISR context.

Deprecated:

Pass a chrono time_point, not an integer millisecond count. For example use Kernel::Clock::now() + 5s rather than Kernel::get_ms_count() + 5000.

try_acquire_until() [2/2]

bool try_acquire_until

(

Kernel::Clock::time_point

abs_time

)

Wait until a Semaphore resource becomes available.

Parameters

abs_time

absolute timeout time, referenced to Kernel::Clock

Returns

true if a resource was acquired, false otherwise.

Note

the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the acquire attempt will time out earlier than specified.

You cannot call this function from ISR context.

release()

osStatus release

(

void

)

Release a Semaphore resource that was obtain with Semaphore::acquire.

Returns

status code that indicates the execution status of the function: osOK the token has been correctly released. osErrorResource the maximum token count has been reached. osErrorParameter internal error.

Note

You may call this function from ISR context.