Open Model Railroad Network (OpenMRN)
Loading...
Searching...
No Matches
Classes | Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
BlockOrWakeUp< Critical > Class Template Reference

A synchronization primitive for device drivers, where execution has to happen in an interrupt context and on regular contexts. More...

#include <BlockOrWakeUp.hxx>

Inheritance diagram for BlockOrWakeUp< Critical >:

Classes

struct  CriticalHolder
 RAII class for holding a critical section lock. More...
 
struct  LockHolder
 RAII class for holding a mutex lock that can be upgraded to a critical section lock. More...
 

Public Member Functions

template<class T >
 BlockOrWakeUp (const T &t)
 Constructor.
 
LockHolder holder ()
 Acquires a lock (not critical) and returns an RAII holder object.
 
void notify_from_isr ()
 Called from ISR context to wake up a regular context or a caller waiting.
 
Notifiable * register_notifiable (Notifiable *n)
 Sets the notifiable that will be called from the ISR (or regular) context when there is more data to consume or space to fill with data.
 

Private Member Functions

void single_lock ()
 Locks the mutex (not the critical).
 
void single_unlock ()
 Unlocks the mutex (not the critical).
 

Private Attributes

OSMutex m_
 Mutex holding non-criticla lock.
 
OSSem s_
 Semaphore used to wake up callers.
 
Notifiable * notifiable_
 Notifiable to be woken up when an ISR event happens.
 

Friends

class LockHolder
 
class CriticalHolder
 

Detailed Description

template<class Critical>
class BlockOrWakeUp< Critical >

A synchronization primitive for device drivers, where execution has to happen in an interrupt context and on regular contexts.

Helpful to implement read() and write() calls contending for a single hardware instance / ring buffer queueing inbound and outbound data. Supports the following features:

  • Execution on a single regular context when multiple threads might be contending for this lock.
  • Execution on a single regular context with interrupts disabled.
  • Blocking a regular context until data is available.
  • Waking up a regular context from an interrupt.
  • Registering a Notifiable to be called when a regular context would be woken up.

Critical should be an object (possibly with no member variables for zero size) that has the following functions:

  • void lock() to prevent execution of the given interrupt
  • void unlock() to allow execution of the given interrupt
  • a one-argument constructor or copy constructor.

In some cases, Atomic is a good candidate for Critical.

Definition at line 65 of file BlockOrWakeUp.hxx.

Constructor & Destructor Documentation

◆ BlockOrWakeUp()

template<class Critical >
template<class T >
BlockOrWakeUp< Critical >::BlockOrWakeUp ( const T &  t)
inline

Constructor.

Parameters
tconstructor argument to the underlying Critical object.

Definition at line 72 of file BlockOrWakeUp.hxx.

Member Function Documentation

◆ holder()

template<class Critical >
LockHolder BlockOrWakeUp< Critical >::holder ( )
inline

Acquires a lock (not critical) and returns an RAII holder object.

The lock can then be upgraded to critical as needed.

Returns
the holder object.

Definition at line 182 of file BlockOrWakeUp.hxx.

◆ notify_from_isr()

template<class Critical >
void BlockOrWakeUp< Critical >::notify_from_isr ( )
inline

Called from ISR context to wake up a regular context or a caller waiting.

Definition at line 188 of file BlockOrWakeUp.hxx.

◆ register_notifiable()

template<class Critical >
Notifiable * BlockOrWakeUp< Critical >::register_notifiable ( Notifiable *  n)
inline

Sets the notifiable that will be called from the ISR (or regular) context when there is more data to consume or space to fill with data.

Parameters
nis the notifiable to be called.
Returns
the previous notifiable that was registered. If not nullptr, then the caller must actually invoke it (or assert fail) to avoid deadlocks.

Definition at line 205 of file BlockOrWakeUp.hxx.

◆ single_lock()

template<class Critical >
void BlockOrWakeUp< Critical >::single_lock ( )
inlineprivate

Locks the mutex (not the critical).

Definition at line 214 of file BlockOrWakeUp.hxx.

◆ single_unlock()

template<class Critical >
void BlockOrWakeUp< Critical >::single_unlock ( )
inlineprivate

Unlocks the mutex (not the critical).

Definition at line 219 of file BlockOrWakeUp.hxx.

Friends And Related Symbol Documentation

◆ CriticalHolder

template<class Critical >
friend class CriticalHolder
friend

Definition at line 81 of file BlockOrWakeUp.hxx.

◆ LockHolder

template<class Critical >
friend class LockHolder
friend

Definition at line 80 of file BlockOrWakeUp.hxx.

Member Data Documentation

◆ m_

template<class Critical >
OSMutex BlockOrWakeUp< Critical >::m_
private

Mutex holding non-criticla lock.

Definition at line 225 of file BlockOrWakeUp.hxx.

◆ notifiable_

template<class Critical >
Notifiable* BlockOrWakeUp< Critical >::notifiable_
private

Notifiable to be woken up when an ISR event happens.

Definition at line 229 of file BlockOrWakeUp.hxx.

◆ s_

template<class Critical >
OSSem BlockOrWakeUp< Critical >::s_
private

Semaphore used to wake up callers.

Definition at line 227 of file BlockOrWakeUp.hxx.

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