Semaphores

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

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 1926 of file os-c-api.h.

os_semaphore_counting_create

#define os_semaphore_counting_create   os_semaphore_counting_construct

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

os_semaphore_create

#define os_semaphore_create   os_semaphore_construct

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

os_semaphore_destroy

#define os_semaphore_destroy   os_semaphore_destruct

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

Typedef Documentation

os_semaphore_attr_t

typedef struct os_semaphore_attr_s os_semaphore_attr_t

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

See also

os::rtos::semaphore::count_t

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

os_semaphore_t

typedef struct os_semaphore_s os_semaphore_t

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
	)

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 2140 of file os-c-wrapper.cpp.

{
  assert (attr != nullptr);
  new (attr) semaphore::attributes_binary{ initial_value };
}

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
	)

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 2154 of file os-c-wrapper.cpp.

{
  assert (attr != nullptr);
  new (attr) semaphore::attributes_counting{ max_value, initial_value };
}

os_semaphore_attr_get_binary()

const os_semaphore_attr_t * os_semaphore_attr_get_binary

(

void

)

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 2169 of file os-c-wrapper.cpp.

{
  return (const os_semaphore_attr_t*)&semaphore::initializer_binary;
}

References os::rtos::semaphore::initializer_binary.

os_semaphore_attr_init()

void os_semaphore_attr_init

(

os_semaphore_attr_t *

attr

)

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 2127 of file os-c-wrapper.cpp.

{
  assert (attr != nullptr);
  new (attr) semaphore::attributes{};
}

os_semaphore_binary_construct()

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

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 2203 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  new (semaphore) rtos::semaphore_binary{ name, initial_value };
}

os_semaphore_binary_new()

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

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 2281 of file os-c-wrapper.cpp.

{
  return reinterpret_cast<os_semaphore_t*> (
      new rtos::semaphore_binary{ name, initial_value });
}

os_semaphore_construct()

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

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 2183 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  if (attr == nullptr)
    {
      attr = (const os_semaphore_attr_t*)&semaphore::initializer_binary;
    }
  new (semaphore) rtos::semaphore{ name, (const semaphore::attributes&)*attr };
}

References os::rtos::semaphore::initializer_binary.

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
	)

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 2219 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  new (semaphore) rtos::semaphore_counting{ name, max_value, initial_value };
}

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
	)

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 2302 of file os-c-wrapper.cpp.

{
  return reinterpret_cast<os_semaphore_t*> (
      new rtos::semaphore_counting{ name, max_value, initial_value });
}

os_semaphore_delete()

void os_semaphore_delete

(

os_semaphore_t *

semaphore

)

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 2325 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  delete reinterpret_cast<rtos::semaphore*> (semaphore);
}

os_semaphore_destruct()

void os_semaphore_destruct

(

os_semaphore_t *

semaphore

)

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 2237 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  (reinterpret_cast<rtos::semaphore&> (*semaphore)).~semaphore ();
}

os_semaphore_get_initial_value()

os_semaphore_count_t os_semaphore_get_initial_value

(

os_semaphore_t *

semaphore

)

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 2437 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (os_semaphore_count_t)(reinterpret_cast<rtos::semaphore&> (
                                    *semaphore))
      .initial_value ();
}

os_semaphore_get_max_value()

os_semaphore_count_t os_semaphore_get_max_value

(

os_semaphore_t *

semaphore

)

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 2452 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (os_semaphore_count_t)(reinterpret_cast<rtos::semaphore&> (
                                    *semaphore))
      .max_value ();
}

os_semaphore_get_name()

const char * os_semaphore_get_name

(

os_semaphore_t *

semaphore

)

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 2338 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (reinterpret_cast<rtos::semaphore&> (*semaphore)).name ();
}

os_semaphore_get_value()

os_semaphore_count_t os_semaphore_get_value

(

os_semaphore_t *

semaphore

)

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 2408 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (os_semaphore_count_t)(reinterpret_cast<rtos::semaphore&> (
                                    *semaphore))
      .value ();
}

os_semaphore_new()

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

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 2257 of file os-c-wrapper.cpp.

{
  if (attr == nullptr)
    {
      attr = (const os_semaphore_attr_t*)&semaphore::initializer_binary;
    }
  return reinterpret_cast<os_semaphore_t*> (
      new rtos::semaphore{ name, (const semaphore::attributes&)*attr });
}

References os::rtos::semaphore::initializer_binary.

os_semaphore_post()

os_result_t os_semaphore_post

(

os_semaphore_t *

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 2351 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::semaphore&> (*semaphore))
      .post ();
}

os_semaphore_reset()

os_result_t os_semaphore_reset

(

os_semaphore_t *

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 2423 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::semaphore&> (*semaphore))
      .reset ();
}

os_semaphore_timed_wait()

os_result_t os_semaphore_timed_wait	(	os_semaphore_t *	semaphore,
		os_clock_duration_t	timeout
	)

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 2393 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::semaphore&> (*semaphore))
      .timed_wait (timeout);
}

os_semaphore_try_wait()

os_result_t os_semaphore_try_wait

(

os_semaphore_t *

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 2379 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::semaphore&> (*semaphore))
      .try_wait ();
}

os_semaphore_wait()

os_result_t os_semaphore_wait

(

os_semaphore_t *

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.
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 2365 of file os-c-wrapper.cpp.

{
  assert (semaphore != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::semaphore&> (*semaphore))
      .wait ();
}

References wait().