S3FC project page S3FC home page
Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

s3_fifo_queue Class Template Reference

FIFO (First-In First-Out) queue that owns its contents and allows consumers and producers to mutate and inspect data in-place. More...

#include <s3_fifo_queue.h>

Inheritance diagram for s3_fifo_queue:

Inheritance graph
[legend]
Collaboration diagram for s3_fifo_queue:

Collaboration graph
[legend]
List of all members.

Public Methods

 s3_fifo_queue (unsigned int n_num_slots)
 Construct a FIFO, specifying the size. More...

virtual ~s3_fifo_queue ()
 Destructor. More...

bool empty () const
 Check and return whether this queue is empty. More...

bool full () const
 Check and return whether this queue is full. More...

unsigned int size () const
 Return number of elements in queue. More...

T * open_input ()
 Regular open input. More...

T * nbl_open_input ()
 Non-blocking open input. More...

void close_input (const T *ptr)
 Release a previously-acquired production slot. More...

T * open_output ()
 Regular open output. More...

T * nbl_open_output ()
 Non-blocking open output. More...

void close_output (const T *ptr)
 Release a previously-acquired consumption slot. More...

void show_status (const char *str=0, int slot=-1) const
 Shows status of a fifo queue. More...

unsigned int get_capacity (void) const
 Return the total number of slots in the queue. More...


Protected Methods

T * open_input (bool blocking)
 Acquire the candidate production slot. More...

T * open_output (bool blocking)
 Acquire the candidate consumption slot. More...


Protected Attributes

unsigned int num_slots
 Total number of slots. More...

pthread_mutex_t state_lock
 Mutex protecting our p_rdy and c_rdy variables. More...

bool * p_rdy
 Flags indicating whether a slot is ready for production. More...

bool * c_rdy
 Flags indicating whether a slot is ready for consumption. More...

pthread_cond_t p_rdy_changed
 Condition varible that gets set when any p_rdy flag changes to true. More...

pthread_cond_t c_rdy_changed
 Condition variable that gets set when any c_rdy flag changes to true. More...

unsigned int p_candidate
 Index of the slot that is to be used next for production. More...

unsigned int c_candidate
 Index of the slot that is to be used next for output. More...

T * slots
 Buffer holding num_slots data slots. More...

Detailed Description

template<typename T>
class s3_fifo_queue< T >

FIFO (First-In First-Out) queue that owns its contents and allows consumers and producers to mutate and inspect data in-place.

An arbitrary number (limited by the size and content) of producers can gain exclusive write access to buffer slots at the tail of the queue, and an arbitrary number of consumers can gain exclusive read access to buffer slots at the head of the queue. Templated on a single type, T, indicating the type of data stored in the queue.

Definition at line 61 of file s3_fifo_queue.h.

Constructor & Destructor Documentation

template<typename T>
s3_fifo_queue< T >::s3_fifo_queue (  unsigned int    n_num_slots )  [inline]
 

Construct a FIFO, specifying the size.

Parameters:
n_num_slots  Size (number of slots) in the FIFO.

Definition at line 109 of file s3_fifo_queue.h.

template<typename T>
virtual s3_fifo_queue< T >::~s3_fifo_queue (    )  [inline, virtual]
 

Destructor.

Clean all the thread variables.

Definition at line 132 of file s3_fifo_queue.h.

Member Function Documentation

template<typename T>
void s3_fifo_queue< T >::close_input (  const T *    ptr )  [inline, virtual]
 

Release a previously-acquired production slot.

Parameters:
ptr  Pointer returned by open_input when slot was opened. Returns with no effect when passed a null pointer. 
      p_rdy[n] = false
      c_rdy[n] = true
      signal(c_rdy_changed)

Implements s3_inplace_fifo_base.

Definition at line 275 of file s3_fifo_queue.h.

template<typename T>
void s3_fifo_queue< T >::close_output (  const T *    ptr )  [inline, virtual]
 

Release a previously-acquired consumption slot.

Parameters:
ptr  Pointer returned by open_output when slot was opened. Returns with no effect when passed a null pointer. 
      c_rdy[n] = false
      p_rdy[n] = true
      signal(p_rdy_changed)

Implements s3_inplace_fifo_base.

Definition at line 380 of file s3_fifo_queue.h.

template<typename T>
bool s3_fifo_queue< T >::empty (    )  const [inline, virtual]
 

Check and return whether this queue is empty.

It is considered empty when the next candidate consumption slot is unavailable.

Implements s3_fifo_base.

Definition at line 146 of file s3_fifo_queue.h.

Referenced by s3_post_office::main_loop.

template<typename T>
bool s3_fifo_queue< T >::full (    )  const [inline, virtual]
 

Check and return whether this queue is full.

It is considered full when the next candidate production slot is unavailable.

Implements s3_fifo_base.

Definition at line 159 of file s3_fifo_queue.h.

template<typename T>
unsigned int s3_fifo_queue< T >::get_capacity (  void    )  const [inline]
 

Return the total number of slots in the queue.

Definition at line 430 of file s3_fifo_queue.h.

template<typename T>
T* s3_fifo_queue< T >::nbl_open_input (    )  [inline, virtual]
 

Non-blocking open input.

Implements s3_inplace_fifo_base.

Definition at line 260 of file s3_fifo_queue.h.

template<typename T>
T* s3_fifo_queue< T >::nbl_open_output (    )  [inline, virtual]
 

Non-blocking open output.

Implements s3_inplace_fifo_base.

Definition at line 365 of file s3_fifo_queue.h.

template<typename T>
T* s3_fifo_queue< T >::open_input (    )  [inline, virtual]
 

Regular open input.

Implements s3_inplace_fifo_base.

Definition at line 253 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::nbl_open_input, and s3_fifo_queue< s3_txport_data< s3_message > >::open_input.

template<typename T>
T* s3_fifo_queue< T >::open_input (  bool    blocking )  [inline, protected]
 

Acquire the candidate production slot.

The candidate slot is the next available slot in the queue, so when a producer calls the open_input method, they will be given a pointer to a slot that they can insert data into. (ie open for input into the queue). In the case where all slots are exhausted, the behaviour depends on the value of blocking: - true Block the caller until the candidate slot becomes available - false Return a null pointer (0).

If the candidate slot is immediately available, or becomes available while a caller is waiting, a pointer to the slot element is returned. This pointer should be passed to close_input when production on this slot is complete.

Parameters:
blocking  Blocking flag.
Returns:
Pointer to start of data (owned by queue) or null pointer in the case where all slots are exhausted. 
      while (1):
        if p_rdy[p_candidate]:
          p_rdy[p_candidate] = false
        return p_candidate++
   else:
     if blocking:
       condition_wait(p_rdy_changed)
     else:
       return 0

Definition at line 213 of file s3_fifo_queue.h.

template<typename T>
T* s3_fifo_queue< T >::open_output (    )  [inline, virtual]
 

Regular open output.

Implements s3_inplace_fifo_base.

Definition at line 358 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::nbl_open_output, and s3_fifo_queue< s3_txport_data< s3_message > >::open_output.

template<typename T>
T* s3_fifo_queue< T >::open_output (  bool    blocking )  [inline, protected]
 

Acquire the candidate consumption slot.

The candidate slot is the next available slot in the queue, so when a consumer calls the open_output method, they will be given a pointer to a slot that they can retrieve data from. (ie open for output from the queue) In the case where all slots are exhausted, the behaviour depends on the value of blocking: - true Block the caller until the candidate slot becomes available - false Return a null pointer (0).

A pointer to the slot element is returned and should be passed to close_output when consumption on this slot is complete.

Parameters:
blocking  Blocking flag.
Returns:
Pointer to start of data (owned by queue) or null pointer. 
      while (1):
        if c_rdy[c_candidate]:
        c_rdy[c_candidate] = false
        return c_candidate++
      else:
     if blocking:
       condition_wait(c_rdy_changed)
     else:
       return 0

Definition at line 316 of file s3_fifo_queue.h.

template<typename T>
void s3_fifo_queue< T >::show_status (  const char *    str = 0,
int    slot = -1
)  const [inline]
 

Shows status of a fifo queue.

Each of the slots in a queue is checked and five possible values are printed. For a producer slot, 'P' means that a slot is ready for production and 'p' means a slot is not ready for production. For a comsumer slot, 'C' means ready for consumption and 'c' means not ready for comsumption. Look at the c_rdy and p_rdy member functions too. If it prints an '!' it has another unknown weird state.

Definition at line 404 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::close_input, s3_fifo_queue< s3_txport_data< s3_message > >::close_output, s3_fifo_queue< s3_txport_data< s3_message > >::open_input, and s3_fifo_queue< s3_txport_data< s3_message > >::open_output.

template<typename T>
unsigned int s3_fifo_queue< T >::size (    )  const [inline, virtual]
 

Return number of elements in queue.

A count of the number of consumable slots is returned.

Returns:
The number of items in the queue ready for consumption.

Implements s3_fifo_base.

Definition at line 172 of file s3_fifo_queue.h.

Member Data Documentation

template<typename T>
unsigned int s3_fifo_queue::c_candidate [protected]
 

Index of the slot that is to be used next for output.

Definition at line 99 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::empty, s3_fifo_queue< s3_txport_data< s3_message > >::open_output, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, and s3_fifo_queue< s3_txport_data< s3_message > >::show_status.

template<typename T>
bool* s3_fifo_queue::c_rdy [protected]
 

Flags indicating whether a slot is ready for consumption.

Each flag corresponds to a single slot. For true it is ready.

Definition at line 81 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::close_input, s3_fifo_queue< s3_txport_data< s3_message > >::close_output, s3_fifo_queue< s3_txport_data< s3_message > >::empty, s3_fifo_queue< s3_txport_data< s3_message > >::open_output, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, s3_fifo_queue< s3_txport_data< s3_message > >::show_status, s3_fifo_queue< s3_txport_data< s3_message > >::size, and s3_fifo_queue< s3_txport_data< s3_message > >::~s3_fifo_queue.

template<typename T>
pthread_cond_t s3_fifo_queue::c_rdy_changed [protected]
 

Condition variable that gets set when any c_rdy flag changes to true.

Definition at line 91 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::close_input, s3_fifo_queue< s3_txport_data< s3_message > >::open_output, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, and s3_fifo_queue< s3_txport_data< s3_message > >::~s3_fifo_queue.

template<typename T>
unsigned int s3_fifo_queue::num_slots [protected]
 

Total number of slots.

Definition at line 67 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::get_capacity, s3_fifo_queue< s3_txport_data< s3_message > >::open_input, s3_fifo_queue< s3_txport_data< s3_message > >::open_output, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, s3_fifo_queue< s3_txport_data< s3_message > >::show_status, and s3_fifo_queue< s3_txport_data< s3_message > >::size.

template<typename T>
unsigned int s3_fifo_queue::p_candidate [protected]
 

Index of the slot that is to be used next for production.

Definition at line 95 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::full, s3_fifo_queue< s3_txport_data< s3_message > >::open_input, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, and s3_fifo_queue< s3_txport_data< s3_message > >::show_status.

template<typename T>
bool* s3_fifo_queue::p_rdy [protected]
 

Flags indicating whether a slot is ready for production.

Each flag corresponds to a single slot. For true, it is ready.

Definition at line 76 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::close_input, s3_fifo_queue< s3_txport_data< s3_message > >::close_output, s3_fifo_queue< s3_txport_data< s3_message > >::full, s3_fifo_queue< s3_txport_data< s3_message > >::open_input, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, s3_fifo_queue< s3_txport_data< s3_message > >::show_status, and s3_fifo_queue< s3_txport_data< s3_message > >::~s3_fifo_queue.

template<typename T>
pthread_cond_t s3_fifo_queue::p_rdy_changed [protected]
 

Condition varible that gets set when any p_rdy flag changes to true.

Definition at line 86 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::close_output, s3_fifo_queue< s3_txport_data< s3_message > >::open_input, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, and s3_fifo_queue< s3_txport_data< s3_message > >::~s3_fifo_queue.

template<typename T>
T* s3_fifo_queue::slots [protected]
 

Buffer holding num_slots data slots.

Definition at line 103 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::close_input, s3_fifo_queue< s3_txport_data< s3_message > >::close_output, s3_fifo_queue< s3_txport_data< s3_message > >::open_input, s3_fifo_queue< s3_txport_data< s3_message > >::open_output, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, and s3_fifo_queue< s3_txport_data< s3_message > >::~s3_fifo_queue.

template<typename T>
pthread_mutex_t s3_fifo_queue::state_lock [protected]
 

Mutex protecting our p_rdy and c_rdy variables.

Definition at line 71 of file s3_fifo_queue.h.

Referenced by s3_fifo_queue< s3_txport_data< s3_message > >::close_input, s3_fifo_queue< s3_txport_data< s3_message > >::close_output, s3_fifo_queue< s3_txport_data< s3_message > >::empty, s3_fifo_queue< s3_txport_data< s3_message > >::full, s3_fifo_queue< s3_txport_data< s3_message > >::open_input, s3_fifo_queue< s3_txport_data< s3_message > >::open_output, s3_fifo_queue< s3_txport_data< s3_message > >::s3_fifo_queue, s3_fifo_queue< s3_txport_data< s3_message > >::size, and s3_fifo_queue< s3_txport_data< s3_message > >::~s3_fifo_queue.

The documentation for this class was generated from the following file:
Send comments to: s3fc@stonethree.com SourceForge Logo