class Fifo

Class Fifo: implements Fifos in shared memory that allows user processes to access for read and write.

Public Methods

member functions to create/delete fifos

Member functions to access/change status of the fifo

Operation for reading/writing/modifying the fifo

Public Members

enum static class member defining the fifo depth

Documentation

Class Fifo: implements Fifos in shared memory that allows user processes to access for read and write.

Each Fifo is a class whose member functions regulate the access to it. The Fifos have to be accessible to every process that participates in the DD pool, therefore they are located in shared memory. In order to avoid subleties with objects in shared memory, Fifos are very simple objects (no inheritance, no templates, no exceptions, hence no virtual tables).

The shared memory where the Fifos are located is created by a static member function create_fifo_system.

The new operator of the Fifo is overloaded to place a new fifo into a free slot in the shared memory segment.

fifo_sys_header: header at beginning of shared memory segment followed by array of fifos.

Each fifo has internally:
1. a header (a struct) : containing name, type, status, struct mode, nb of processes attached etc etc
2. read/write pointers : point to next location to read/write an array of fifo entries (struct fentry)

Modifications:

enum static class member defining the fifo depth

static class member defining the fifo depth

member functions to create/delete fifos

Fifo( const char* name, const char* type, sFifo_mode mode, int depth = eFifo_depth_max)

Creates a fifo.

Parameters:

name - : const char* specifiying the name of the fifo
type - : currently two types are supported: "STA" and "DYN". Static fifos are never deleted, even if no process is attached to the fifo. "DYN" fifos are deleted, when the last process detaches from it.
mode - : mode of the fifo, a C structure.
depth - : normally not specified, all fifos are of the same depth.

~Fifo()

dtor

void* operator new(size_t size, Fifo_system* the_system, int slot_nb = -1)

new operator. The Fifos have their own new operator, as they are created in the shared memory segment. If there is a free fifo slot available, returns pointer to it, otherwise the NULL pointer is returned.

Parameters:

size - : size of the fifo - must be given because of C++ syntax
the_system - : the fifo system in which we create a fifo (i.e. the starting address of the shared memory segment)
slot_nb - : the array index of the fifo. If equal to -1, then we leave it to the system to decide where to place the fifo, if greater equal zero, then we want the fifo to be created in this slot.

Returns:

pointer to the fifo or NULL

void operator delete(void* ptr, size_t size)

Overloaded delete operator. As the handling of the fifo detachment are done in the destructor, this member function does not do anything (we do not delete any shared memory when the fifo is destroyed).

Member functions to access/change status of the fifo

void set_status( eFifo_status status )

sets the status of the fifo

void activate()

Activates the fifo, ie. declares it ready to accept events

void deactivate()

Deactivates the fifo. If several processes share the fifo, then it gets only deactivated after the last processes declares it deactivated.

int in_use()

Returns -1 if the fifo is in use

int is_active()

Returns -1 if the fifo is active

void set_protection( eFifo_protection eNew_protection)

Sets the protection of the fifo.

Parameters:

eFifo_protection - : fifo_unprotected: If the fifo looks suspicious to the garbage demon, then it will be removed. fifo_protected: the garbage demon will never remove the fifo, even if is shows no activity or cloggs the system

BOOL is_protected()

returns true if the fifo is protected

fifo_header get_header()

Returns the fifo header (a C structure)

sFifo_mode get_mode()

Returns the mode of the fifo (a C structure)

int set_mode(sFifo_mode &new_mode)

Sets the mode of the fifo

void set_reqcnt( const int icnt )

Sets the request count of the fifo. The request count specifies how many events are put into the fifo maximally. This allows to regulate the flow of the events in the system.

Parameters:

icnt - : integer, greater zero.

void set_prescale( const int iPs )

Sets the prescale of the fifo. If prescale is greater than zero, events that fulfill the filter requirements of the fifo will be prescaled.

void print_header()

Prints the header to cout.

void dump()

Dumps the entire fifo to cout. Note: if the fifo is deep and full of events this can produce a lot of output.

void print()

Prints the fifo, ie. prints the header and then dumps the fifo

int get_nproc_waiting()

Returns the number of processes that are waiting for events in this fifo.

int get_nproc_attached() const

Returns the number of processes that are attached to this fifo

char* get_name()

Returns the name of the fifo

int get_nopin() const

Returns the number of input operations on this fifo

int get_nopout() const

Returns the number of output operations for this fifo If the fifo is empty, then nopin and nopout should be equal (unless it is the INPUT fifo)

int get_cnt() const

Returns the number of events in the fifo.

int get_number() const

Returns the number of the fifo, ie. its index in the fifo array in shared memory.

Operation for reading/writing/modifying the fifo

int lock()

Locks the fifo - do not use - this will become obsolete!!!

int unlock()

Unlocks the fifo - do not use - this will become obsolete!!!

int write( Fifo_entry &fev )

Writes the fifo entry fev into the fifo - returns 0 if success.

int read( Fifo_entry &fev, eFifo_wait_mode mode = sleep_mode )

Reads the next fifo entry fev from the fifo.

Parameters:

fev - : reference for the fifo entry @mode, in which the fifo is supposed to be read. Default is fall asleep until an event is available.

BOOL evaluate( const Fifo_system* theSystem, const Fifo_entry &fev )

Evaluates the header of the fifo to see which criteria should be applied for deciding whether or not an event should be put into a fifo.
The following possibilities are currently implemented:

• Every event is accepted by the fifo.
• The fifo has a filter on, call the member function Fifo::filter.
• The fifo is in request mode, decide whether the event is really requested. If the request count is smaller/equal zero, then look whether there is a process waiting for an event. If the request count is bigger zero, then look whether there are already the number of requested entries in the fifo.
• The fifo has a non-zero prescale factor.

Returns:

boolean, true if the event is put into the fifo.

BOOL filter( const Fifo_entry &fev )

Fifo filter that decides whether or not an event will be put into the fifo. This routine specifies how the control words of the fifo and the control words of the fifo entry have to match in order for the fifo entry to be put into the fifo. As this routine might be changed by the user, it is kept in a separate file called fifo_evaluate.cc.
The default implementation requires that:

• If a control word is -1, then it is considered to be not tested.
• One (and only one) of the following requirements have to be fulfilled:
  1. ctlw1 or ctlw2 have to match exactly (test for equality)
  2. ctlb1 or ctlb2 have to be non-zero in the bit-wise test (operator &).

Returns:

boolean, true if the fifo has to be put into the fifo.

This class has no child classes.

Friends:

class Fifo_system

Author:

C.Witzig
Date: Nov 18, 1997

Version:

Last update: May 25, 98

Alphabetic index HTML hierarchy of classes or Java