C API semaphore definitions. More...

Classes
struct	os_semaphore_attr_s
	Semaphore attributes. More...

struct	os_semaphore_s
	Semaphore object storage. More...

Typedefs
typedef struct os_semaphore_attr_s	os_semaphore_attr_t
	Semaphore attributes.

typedef int16_t	os_semaphore_count_t
	Type of variables holding semaphore counts.

typedef struct os_semaphore_s	os_semaphore_t
	Semaphore object storage.

Semaphore Attributes Functions
void	os_semaphore_attr_init (os_semaphore_attr_t *attr)
	Initialise the counting semaphore attributes.

void	os_semaphore_attr_binary_init (os_semaphore_attr_t *attr, const os_semaphore_count_t initial_value)
	Initialise the binary semaphore attributes.

void	os_semaphore_attr_counting_init (os_semaphore_attr_t *attr, const os_semaphore_count_t max_value, const os_semaphore_count_t initial_value)
	Initialise the counting semaphore attributes.

const os_semaphore_attr_t *	os_semaphore_attr_get_binary (void)
	Get a binary semaphore attributes object instance.

Semaphore Creation Functions
void	os_semaphore_construct (os_semaphore_t semaphore, const char name, const os_semaphore_attr_t *attr)
	Construct a statically allocated semaphore object instance.

void	os_semaphore_binary_construct (os_semaphore_t semaphore, const char name, const os_semaphore_count_t initial_value)
	Construct a statically allocated binary semaphore object instance.

void	os_semaphore_counting_construct (os_semaphore_t semaphore, const char name, const os_semaphore_count_t max_value, const os_semaphore_count_t initial_value)
	Construct a statically allocated counting semaphore object instance.

void	os_semaphore_destruct (os_semaphore_t *semaphore)
	Destruct the statically allocated semaphore object instance.

os_semaphore_t *	os_semaphore_new (const char name, const os_semaphore_attr_t attr)
	Allocated a semaphore object instance and construct it.

os_semaphore_t *	os_semaphore_binary_new (const char *name, const os_semaphore_count_t initial_value)
	Allocate a binary semaphore object instance and construct it.

os_semaphore_t *	os_semaphore_counting_new (const char *name, const os_semaphore_count_t max_value, const os_semaphore_count_t initial_value)
	Allocate a counting semaphore object instance and construct it.

void	os_semaphore_delete (os_semaphore_t *semaphore)
	Destruct the semaphore object instance.

Semaphore Functions
const char *	os_semaphore_get_name (os_semaphore_t *semaphore)
	Get the semaphore name.

os_result_t	os_semaphore_post (os_semaphore_t *semaphore)
	Post (unlock) the semaphore.

os_result_t	os_semaphore_wait (os_semaphore_t *semaphore)
	Lock the semaphore, possibly waiting.

os_result_t	os_semaphore_try_wait (os_semaphore_t *semaphore)
	Try to lock the semaphore.

os_result_t	os_semaphore_timed_wait (os_semaphore_t *semaphore, os_clock_duration_t timeout)
	Timed wait to lock the semaphore.

os_semaphore_count_t	os_semaphore_get_value (os_semaphore_t *semaphore)
	Get the semaphore count value.

os_result_t	os_semaphore_reset (os_semaphore_t *semaphore)
	Reset the semaphore.

os_semaphore_count_t	os_semaphore_get_initial_value (os_semaphore_t *semaphore)
	Get the semaphore initial count value.

os_semaphore_count_t	os_semaphore_get_max_value (os_semaphore_t *semaphore)
	Get the semaphore maximum count value.

Compatibility Macros
#define	os_semaphore_create os_semaphore_construct

#define	os_semaphore_binary_create os_semaphore_binary_construct

#define	os_semaphore_counting_create os_semaphore_counting_construct

#define	os_semaphore_destroy os_semaphore_destruct

Detailed Description

C API semaphore definitions.

For the complete definition, see: RTOS C++ API

Examples

int
os_main (int argc, char* argv[])
{
    {
      // Binary semaphore, start at 0.
      os_semaphore_t sp1;
      os_semaphore_binary_construct (&sp1, "sp1", 0);
 
      os_semaphore_post (&sp1);
      os_semaphore_wait (&sp1);
 
      os_semaphore_post (&sp1);
      os_semaphore_try_wait (&sp1);
 
      os_semaphore_post (&sp1);
      os_semaphore_timed_wait (&sp1, 1);
 
      os_semaphore_get_value (&sp1);
 
      os_semaphore_get_initial_value (&sp1);
 
      os_semaphore_reset (&sp1);
 
      name = os_semaphore_get_name (&sp1);
 
      os_semaphore_destruct (&sp1);
    }
 
    {
      // Custom semaphore.
      os_semaphore_attr_t asp2;
      os_semaphore_attr_init (&asp2);
 
      asp2.sm_initial_value = 3;
      asp2.sm_max_value = 7;
      asp2.clock = os_clock_get_rtclock ();
 
      os_semaphore_t sp2;
      os_semaphore_construct (&sp2, "sp2", &asp2);
 
      os_semaphore_destruct (&sp2);
    }
 
    {
      // Counting semaphore, 7 resources, start at 7.
      os_semaphore_t sp3;
      os_semaphore_counting_construct (&sp3, "sp3", 7, 7);
 
      os_semaphore_destruct (&sp3);
    }
 
    {
      // Custom binary semaphore.
      os_semaphore_attr_t asp4;
      os_semaphore_attr_binary_init (&asp4, 0);
      asp4.clock = os_clock_get_rtclock ();
 
      os_semaphore_t sp4;
      os_semaphore_construct (&sp4, "sp4", &asp4);
 
      os_semaphore_destruct (&sp4);
    }
}

Macro Definition Documentation

◆ os_semaphore_binary_create

#define os_semaphore_binary_create os_semaphore_binary_construct

Definition at line 1921 of file os-c-api.h.

◆ os_semaphore_counting_create

#define os_semaphore_counting_create os_semaphore_counting_construct

Definition at line 1922 of file os-c-api.h.

◆ os_semaphore_create

#define os_semaphore_create os_semaphore_construct

Definition at line 1920 of file os-c-api.h.

◆ os_semaphore_destroy

#define os_semaphore_destroy os_semaphore_destruct

Definition at line 1923 of file os-c-api.h.

Typedef Documentation

◆ os_semaphore_attr_t

typedef struct os_semaphore_attr_s os_semaphore_attr_t

Semaphore attributes.

Initialise this structure with os_semaphore_attr_init() and then set any of the individual members directly.

See also: os::rtos::semaphore::attributes

◆ os_semaphore_count_t

typedef int16_t os_semaphore_count_t

Type of variables holding semaphore counts.

See also: os::rtos::semaphore::count_t

Definition at line 1081 of file os-c-decls.h.

◆ os_semaphore_t

typedef struct os_semaphore_s os_semaphore_t

Semaphore object storage.

This C structure has the same size as the C++ os::rtos::semaphore object and must be initialised with os_semaphore_create().

Later on a pointer to it can be used both in C and C++ to refer to the semaphore object instance.

The members of this structure are hidden and should not be used directly, but only through specific functions.

See also: os::rtos::semaphore

Function Documentation

◆ os_semaphore_attr_binary_init()

void os_semaphore_attr_binary_init	(	os_semaphore_attr_t *	attr,
		const os_semaphore_count_t	initial_value
	)

Initialise the binary semaphore attributes.

Parameters

[in]	attr	Pointer to semaphore attributes object instance.
[in]	initial_value	Initial count value.

Returns: Nothing.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::attributes_binary

Definition at line 1949 of file os-c-wrapper.cpp.

◆ os_semaphore_attr_counting_init()

void os_semaphore_attr_counting_init	(	os_semaphore_attr_t *	attr,
		const os_semaphore_count_t	max_value,
		const os_semaphore_count_t	initial_value
	)

Initialise the counting semaphore attributes.

Parameters

[in]	attr	Pointer to semaphore attributes object instance.
[in]	max_value	Maximum count value.
[in]	initial_value	Initial count value.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::attributes_counting

Definition at line 1964 of file os-c-wrapper.cpp.

◆ os_semaphore_attr_get_binary()

const os_semaphore_attr_t * os_semaphore_attr_get_binary ( void )

Get a binary semaphore attributes object instance.

Returns: Pointer to semaphore attributes object instance.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::initializer_binary

Definition at line 1980 of file os-c-wrapper.cpp.

◆ os_semaphore_attr_init()

void os_semaphore_attr_init ( os_semaphore_attr_t * attr )

Initialise the counting semaphore attributes.

Parameters

[in] attr Pointer to semaphore attributes object instance.

Returns: Nothing.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::attributes

Definition at line 1935 of file os-c-wrapper.cpp.

◆ os_semaphore_binary_construct()

void os_semaphore_binary_construct	(	os_semaphore_t *	semaphore,
		const char *	name,
		const os_semaphore_count_t	initial_value
	)

Construct a statically allocated binary semaphore object instance.

Parameters

[in]	semaphore	Pointer to semaphore object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	initial_value	Initial count value.

Returns: Nothing.

Note: Must be paired with os_semaphore_destruct().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore_binary

Definition at line 2015 of file os-c-wrapper.cpp.

◆ os_semaphore_binary_new()

os_semaphore_t * os_semaphore_binary_new	(	const char *	name,
		const os_semaphore_count_t	initial_value
	)

Allocate a binary semaphore object instance and construct it.

Parameters

[in]	name	Pointer to name (may be NULL).
[in]	initial_value	Initial count value.

Returns: Pointer to new semaphore object instance.

Dynamically allocate the binary semaphore object instance using the RTOS system allocator and construct it.

Note: Equivalent of C++ new semaphore_binary(...).; Must be paired with os_semaphore_delete().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore_binary

Definition at line 2095 of file os-c-wrapper.cpp.

◆ os_semaphore_construct()

void os_semaphore_construct	(	os_semaphore_t *	semaphore,
		const char *	name,
		const os_semaphore_attr_t *	attr
	)

Construct a statically allocated semaphore object instance.

Parameters

[in]	semaphore	Pointer to semaphore object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	attr	Pointer to attributes (may be NULL).

Returns: Nothing.

Note: Must be paired with os_semaphore_destruct().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore

Definition at line 1994 of file os-c-wrapper.cpp.

◆ os_semaphore_counting_construct()

void os_semaphore_counting_construct	(	os_semaphore_t *	semaphore,
		const char *	name,
		const os_semaphore_count_t	max_value,
		const os_semaphore_count_t	initial_value
	)

Construct a statically allocated counting semaphore object instance.

Parameters

[in]	semaphore	Pointer to semaphore object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	max_value	Maximum count value.
[in]	initial_value	Initial count value.

Returns: Nothing.

Note: Must be paired with os_semaphore_destruct().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore_counting

Definition at line 2032 of file os-c-wrapper.cpp.

◆ os_semaphore_counting_new()

os_semaphore_t * os_semaphore_counting_new	(	const char *	name,
		const os_semaphore_count_t	max_value,
		const os_semaphore_count_t	initial_value
	)

Allocate a counting semaphore object instance and construct it.

Parameters

[in]	name	Pointer to name (may be NULL).
[in]	max_value	Maximum count value.
[in]	initial_value	Initial count value.

Returns: Pointer to new semaphore object instance.

Dynamically allocate the counting semaphore object instance using the RTOS system allocator and construct it.

Note: Equivalent of C++ new semaphore_counting(...).; Must be paired with os_semaphore_delete().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore_counting

Definition at line 2116 of file os-c-wrapper.cpp.

◆ os_semaphore_delete()

void os_semaphore_delete ( os_semaphore_t * semaphore )

Destruct the semaphore object instance.

Parameters

[in] semaphore Pointer to semaphore object instance.

Returns: Nothing.

Destruct the semaphore and deallocate the dynamically allocated space using the RTOS system allocator.

Note: Equivalent of C++ delete ptr_semaphore.; Must be paired with os_semaphore_new() or os_semaphore_binary_new() or os_semaphore_counting_new().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore

Definition at line 2139 of file os-c-wrapper.cpp.

◆ os_semaphore_destruct()

void os_semaphore_destruct ( os_semaphore_t * semaphore )

Destruct the statically allocated semaphore object instance.

Parameters

[in] semaphore Pointer to semaphore object instance.

Returns: Nothing.

Note: Must be paired with os_semaphore_construct() or os_semaphore_binary_construct() or os_semaphore_counting_construct().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore

Definition at line 2051 of file os-c-wrapper.cpp.

◆ os_semaphore_get_initial_value()

os_semaphore_count_t os_semaphore_get_initial_value ( os_semaphore_t * semaphore )

Get the semaphore initial count value.

Parameters

[in] semaphore Pointer to semaphore object instance.

Returns: The numeric value set from attributes.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::initial_value()

Definition at line 2244 of file os-c-wrapper.cpp.

◆ os_semaphore_get_max_value()

os_semaphore_count_t os_semaphore_get_max_value ( os_semaphore_t * semaphore )

Get the semaphore maximum count value.

Parameters

[in] semaphore Pointer to semaphore object instance.

Returns: The numeric value set from attributes.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::max_value()

Definition at line 2257 of file os-c-wrapper.cpp.

◆ os_semaphore_get_name()

const char * os_semaphore_get_name ( os_semaphore_t * semaphore )

Get the semaphore name.

Parameters

[in] semaphore Pointer to semaphore object instance.

Returns: Null terminated string.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::name()

Definition at line 2152 of file os-c-wrapper.cpp.

◆ os_semaphore_get_value()

os_semaphore_count_t os_semaphore_get_value ( os_semaphore_t * semaphore )

Get the semaphore count value.

Parameters

[in] semaphore Pointer to semaphore object instance.

Returns: The semaphore count value.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::value()

Definition at line 2218 of file os-c-wrapper.cpp.

◆ os_semaphore_new()

os_semaphore_t * os_semaphore_new	(	const char *	name,
		const os_semaphore_attr_t *	attr
	)

Allocated a semaphore object instance and construct it.

Parameters

[in]	name	Pointer to name (may be NULL).
[in]	attr	Pointer to attributes (may be NULL).

Returns: Pointer to new semaphore object instance.

Dynamically allocate the semaphore object instance using the RTOS system allocator and construct it.

Note: Equivalent of C++ new semaphore(...).; Must be paired with os_semaphore_delete().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore

Definition at line 2071 of file os-c-wrapper.cpp.

◆ os_semaphore_post()

os_result_t os_semaphore_post ( os_semaphore_t * semaphore )

Post (unlock) the semaphore.

Parameters

[in] semaphore Pointer to semaphore object instance.

Return values

os_ok	The semaphore was posted.
EAGAIN	The maximum count value was exceeded.
ENOTRECOVERABLE	The semaphore could not be posted (extension to POSIX).

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::post()

Definition at line 2165 of file os-c-wrapper.cpp.

◆ os_semaphore_reset()

os_result_t os_semaphore_reset ( os_semaphore_t * semaphore )

Reset the semaphore.

Parameters

[in] semaphore Pointer to semaphore object instance.

Return values

os_ok	The semaphore was reset.
EPERM	Cannot be invoked from an Interrupt Service Routines.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::reset()

Definition at line 2231 of file os-c-wrapper.cpp.

◆ os_semaphore_timed_wait()

os_result_t os_semaphore_timed_wait	(	os_semaphore_t *	semaphore,
		os_clock_duration_t	timeout
	)

Timed wait to lock the semaphore.

Parameters

[in]	semaphore	Pointer to semaphore object instance.
[in]	timeout	Timeout to wait.

Return values

os_ok	The calling process successfully performed the semaphore lock operation.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	Invalid timeout (POSIX limits the timeout to 1000 million ns)
ETIMEDOUT	The semaphore could not be locked before the specified timeout expired.
ENOTRECOVERABLE	Semaphore wait failed (extension to POSIX).
EDEADLK	A deadlock condition was detected.
EINTR	The operation was interrupted.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::timed_wait()

Definition at line 2204 of file os-c-wrapper.cpp.

◆ os_semaphore_try_wait()

os_result_t os_semaphore_try_wait ( os_semaphore_t * semaphore )

Try to lock the semaphore.

Parameters

[in] semaphore Pointer to semaphore object instance.

Return values

os_ok	The calling process successfully performed the semaphore lock operation.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EWOULDBLOCK	The semaphore was already locked.
ENOTRECOVERABLE	Semaphore wait failed (extension to POSIX).
EDEADLK	A deadlock condition was detected.
EINTR	The operation was interrupted.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::try_wait()

Definition at line 2191 of file os-c-wrapper.cpp.

◆ os_semaphore_wait()

os_result_t os_semaphore_wait ( os_semaphore_t * semaphore )

Lock the semaphore, possibly waiting.

Parameters

[in] semaphore Pointer to semaphore object instance.

Return values

os_ok	The calling process successfully performed the semaphore lock operation.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	Semaphore wait failed (extension to POSIX).
EDEADLK	A deadlock condition was detected.
EINTR	The operation was interrupted.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::semaphore::wait()

Definition at line 2178 of file os-c-wrapper.cpp.

Classes

Typedefs

Semaphore Attributes Functions

Semaphore Creation Functions

Semaphore Functions

Compatibility Macros

Detailed Description

Macro Definition Documentation

◆ os_semaphore_binary_create

◆ os_semaphore_counting_create

◆ os_semaphore_create

◆ os_semaphore_destroy

Typedef Documentation

◆ os_semaphore_attr_t

◆ os_semaphore_count_t

◆ os_semaphore_t

Function Documentation

◆ os_semaphore_attr_binary_init()

◆ os_semaphore_attr_counting_init()

◆ os_semaphore_attr_get_binary()

◆ os_semaphore_attr_init()

◆ os_semaphore_binary_construct()

◆ os_semaphore_binary_new()

◆ os_semaphore_construct()

◆ os_semaphore_counting_construct()

◆ os_semaphore_counting_new()

◆ os_semaphore_delete()

◆ os_semaphore_destruct()

◆ os_semaphore_get_initial_value()

◆ os_semaphore_get_max_value()

◆ os_semaphore_get_name()

◆ os_semaphore_get_value()

◆ os_semaphore_new()

◆ os_semaphore_post()

◆ os_semaphore_reset()

◆ os_semaphore_timed_wait()

◆ os_semaphore_try_wait()

◆ os_semaphore_wait()