Loading...
Searching...
No Matches
L4::Semaphore Struct Reference

C++ Kernel-provided semaphore interface, see Kernel-provided semaphore for the C interface. More...

`#include <semaphore>`

Inheritance diagram for L4::Semaphore:
Collaboration diagram for L4::Semaphore:

## Public Member Functions

l4_msgtag_t | up (l4_utcb_t *utcb=l4_utcb()) noexcept
| Semaphore up operation (wrapper for trigger()).
l4_msgtag_t | down (l4_timeout_t timeout=L4_IPC_NEVER, l4_utcb_t *utcb=l4_utcb()) noexcept
| Semaphore down operation.
Public Member Functions inherited from L4::Triggerable
l4_msgtag_t | trigger (l4_utcb_t *utcb=l4_utcb()) noexcept
| Trigger the object.
Public Member Functions inherited from L4::Irq_eoi
l4_msgtag_t | unmask (unsigned irqnum, l4_umword_t *label=0, l4_timeout_t to=L4_IPC_NEVER, l4_utcb_t *utcb=l4_utcb()) noexcept
| Unmask the given interrupt line.

## Additional Inherited Members

Protected Types inherited from L4::Kobject_t< Semaphore, Triggerable, L4_PROTO_SEMAPHORE >
typedef Semaphore | Class
| The target interface type (inheriting from Kobject_t).
typedef Typeid::Iface< PROTO, Semaphore > | __Iface
| The interface description for the derived class.
typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Triggerable::__Iface_list > | __Iface_list
| The list of all RPC interfaces provided directly or through inheritance.
Protected Types inherited from L4::Kobject_t< Triggerable, Irq_eoi, L4_PROTO_IRQ >
typedef Triggerable | Class
| The target interface type (inheriting from Kobject_t).
typedef Typeid::Iface< PROTO, Triggerable > | __Iface
| The interface description for the derived class.
typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Irq_eoi::__Iface_list > | __Iface_list
| The list of all RPC interfaces provided directly or through inheritance.
Protected Member Functions inherited from L4::Kobject_t< Semaphore, Triggerable, L4_PROTO_SEMAPHORE >
L4::Cap< Class > | c () const noexcept
| Get the capability to ourselves.
Protected Member Functions inherited from L4::Kobject_t< Triggerable, Irq_eoi, L4_PROTO_IRQ >
L4::Cap< Class > | c () const noexcept
| Get the capability to ourselves.
Static Protected Member Functions inherited from L4::Kobject_t< Semaphore, Triggerable, L4_PROTO_SEMAPHORE >
static void | __check_protocols__ () noexcept
| Helper to check for protocol conflicts.
Static Protected Member Functions inherited from L4::Kobject_t< Triggerable, Irq_eoi, L4_PROTO_IRQ >
static void | __check_protocols__ () noexcept
| Helper to check for protocol conflicts.

## Detailed Description

C++ Kernel-provided semaphore interface, see Kernel-provided semaphore for the C interface.

This is the interface for kernel-provided semaphore objects. The object provides the classical functions up() and down() for counting the semaphore and blocking. The semaphore is a Triggerable with respect to the up() function, this means that a semaphore can be bound to an interrupt line at an ICU (L4::Icu) and incoming interrupts increment the semaphore counter.

The down() method decrements the semaphore counter and blocks if the counter is already zero. Blocking on a semaphore may—as all blocking operations—either return successfully, or be aborted due to an expired timeout provided to the down() operation, or due to an L4::Thread::ex_regs() operation with the L4_THREAD_EX_REGS_CANCEL flag set.

A semaphore object is initialized with counter value 0.

The main reason for using a semaphore instead of an L4::Irq is to ensure that incoming trigger signals do not interfere with any open-wait operations, as used for example in a server loop.

Note that this is a kernel-level semaphore primitive that shall be used to implement user-level, application-usable synchronization primitives. For example, use pthread_mutex functions in applications if possible. When implementing a synchronization primitive, please ensure to only use L4::Semaphore in the case of contention, and use atomic operations for the non-contended case.

Definition at line 51 of file semaphore.

## Member Function Documentation

## down()

l4_msgtag_t L4::Semaphore::down | ( | l4_timeout_t | timeout = L4_IPC_NEVER,
|  | l4_utcb_t * | utcb = l4_utcb() )

inlinenoexcept

Semaphore down operation.

Parameters

  timeout | Timeout for blocking the semaphore down operation. Note: The receive timeout of this timeout-pair is significant for blocking, the send part is usually non-blocking.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag. Use l4_error() to check for errors.

Return values

  -L4_EPERM | Insufficient permissions; see precondition.

Precondition
  The invoked Semaphore capability must have the permission L4_CAP_FPAGE_S.

This method decrements the semaphore counter by one, or blocks if the counter is already zero, until either a timeout or cancel condition hits or the counter is increased by an up() operation.

Definition at line 89 of file semaphore.

References L4::Kobject::cap(), and L4_IPC_NEVER.

Here is the call graph for this function:

## up()

l4_msgtag_t L4::Semaphore::up | ( | l4_utcb_t * | utcb = l4_utcb() | ) |

inlinenoexcept

Semaphore up operation (wrapper for trigger()).

Parameters

  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag for a send-only operation, this means there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. Use l4_ipc_error() to check for errors and do not use l4_error().

Increases the semaphore counter by one if it is smaller than an unspecified limit. The unspecified limit is guaranteed to be at least 2^31-1.

Definition at line 67 of file semaphore.

References L4::Triggerable::trigger().

Here is the call graph for this function:

The documentation for this struct was generated from the following file:

- l4/sys/semaphore