class DD

Abstract class of the DD system.

Inheritance:

Public Fields

[more]static const char* const pccDefaultDDName
Default way for the DD system.
[more]static const char* const pccDefaultDDFileName
Default DD tmp file.

Public Methods

[more] Creating and deleting DD systems
[more] Member functions for FIFO manipulations
[more] Coordination and control of the DD system
[more] Inserting and accessing events in the pool
[more] Member functions to set/get process specific parameters
[more] Miscellanous member functions
[more]static void printUnsupportedOperation( const char* operation )
Prints information about an usnupported operation in a given DD version

Public Members

[more] enums as static data members

Protected Fields

[more]BOOL is_local
true if the DD system is local
[more]char* name
name of the system
[more]char* config_file
full pathname of the configuration file (or NULL if not specified)
[more]char* dd_filename
full pathname of the project file (used for IPC resources)
[more]static const char* dd_version
Static string with the DD release name

Documentation

Abstract class of the DD system. This class is the supertype for the DD system. When the system is created, it is decided where it resides and the corresponding subtype created. E.g. the class lDD if we are local, rDD if the system is on another host.

Modifications

o enums as static data members

oenum fill_request_modes
Fill request modes for the req_fev - works bitwise . NOTE: do not confuse this fill mode with the read mode of a fifo by a consumer.

oenum eBroadcast_mode
enums for broadcast modes

oenum eDefault_times
enum with default wait times in ms

oenum eLog_types
enums for error messages. A user might want to modify this.

oenum Signal definitions that the user may want to change
Signal definitions that the user may want to change

o Creating and deleting DD systems

o DD( char* name, char* config_file, const char* dd_filename = DD::pccDefaultDDFileName )
Constructor of the DD system.
Parameters:
name - : name of the system
config_file - : global configuration file with the information on the system wide default values
dd_filename - : (optional) project filename for the DD system
Returns:
Pointer to the created DD system or exception or NULL (if compiled with -DDD_NOEXCEPTION) Note: the user normally doesn't call this routine, but creates the system either with the help of the DD_Factory or the static memberfunction create_dd

ovirtual ~DD()
dtor

ostatic DD* create_dd( const char* name = DD::pccDefaultDDName, const char* mode = "r", const char* config_file = NULL)
Creates a DD system. This static memberfunction is used to create the DD system. First it decides on which host the DD system resides and then creates the proper subclass of DD.
The arguments are:
Parameters:
dd_name - : name of the DD system: If the name is of the form dd@hostname, then the system is created on the remote host hostname.
mode - : "w" to create the DD if it doesn't exits, "r" (=default): attaches to the DD.
config_file - : (optional) configuration file of the DD
Returns:
Pointer to the DD system or NULL

ostatic int remove_dd( DD* theDD )
Enforces the removal of the DD system. See DD_Factory for the difference on delete and removal of a DD.

ostatic BOOL exists(const char* name = DD::pccDefaultDDName )
BOOL - returns true if the system exists (and we are attached to it)

o Member functions for FIFO manipulations

ovirtual Fifo* create_fifo( const char* fifo_name, const char* type = "DYN", Fifo_mode* mode = NULL, int slot_nb = -1) = 0
Creates the fifo (or attaches to it if it exists) named fifo_name.
Parameters:
- fifo_name Name of the fifo
type - "STA" for static fifo, "DYN" for dynamic fifos.
Note that static fifos are not removed when the process detaches, dynamic fifos are removed when the last process that is attached to it detaches.
mode - pointer to an instance of the class Fifo_mode with the information about the mode of the fifo. Default = NULL pointer.
- slot_nb (optional) indicates in which slot of the Fifo_system we want to create the fifo. (This is normally not used and the DD system decides where it wants to create the fifo).
Returns:
Pointer to the Fifo that was created. Note that this fifo can be a real fifo if the DD pool if the pool is local. If the pool is remote, the pointer points to a proxy object with limited capabilities. See rDD::create_fifo for details.

ovirtual int delete_fifo( const char* fifo_name = NULL ) = 0
Deletes the fifo.
Parameters:
- fifo_name normally not specified and we delete the fifo which we created and read the events from the DD system. If we created several fifos, then we delete the last one that we created.
Returns:
ddcSuccess or ddcFailure

ovirtual Fifo_system* get_fifo_system() = 0
returns a pointer to the Fifo_system that belongs to the DD or NULL if the DD system is on a remote host

ovirtual int fifo_exists( const char* fifoname ) const = 0
returns ddcSuccess if the fifo named fifoname exists (or ddcFailure if not)

ovirtual int fifo_active( const char* fifoname ) const = 0
returns ddcSuccess if the fifo named fifoname is active (or ddcFailure if not)

o Coordination and control of the DD system

ovirtual int flush( const int nMsec = eWaitFlush, const int brc_flush = 0 ) = 0
Flushes the DD system. This member function first locks the INPUT fifo such that producers can no longer inject any events into the DD system. Then it loops over all fifos, takes the events out and stores them in the BROADCAST fifo (as the INPUT is locked). Next it waits until all processes are sleeping on the semaphore before it unlocks the INPUT fifo, puts the events in there and unlocks dcom.
Parameters:
nMsec - maximum wait period in milliseconds for the processes to fall asleep
brc_flush - if true propate the flush also to remote DD systems
Returns:
ddcSuccess or ddcFailure (if serious error). If we timed out after nMsec while waiting for the processes to fall asleep, we return the (positive) number of processes that did not fall asleep.

ovirtual int wait4proc( const int nMsec = eWait4ProcDefault ) = 0
Waits until all processes have an empty fifo.
Parameters:
- : nMsec: timeout value
Returns:
ddcSuccess or ddcFailure (if there are processes left that have non-empty fifos

ovirtual int wakeup() = 0
Wakes up all processes that are sleeping on a semaphore. Set the status in dcom to DD_PROC_STATE_DEBLOCKED and call the member function unlock_fifo for every fifo (except the INPUT)
Returns:
ddcSuccess or ddcFailure (if there are still processes that are waiting on the fifo to become non-empty.

ovirtual int prepare_shutdown() = 0
Inform processes about an imminent shutdown of the DD system. Send the DD_SHUTDOWN_SIGNAL to every process attached to the DD system to warn it about an immintent removal of the system.

o Inserting and accessing events in the pool

ovirtual int req_fev( const int size, Fifo_entry &fev, const int mode = SLEEP, const int min_cnt = 1 ) = 0
Requests an free buffer in the DD system. Upon success req_fev returns a reference to available Fifo_entry of the requested size.
Parameters:
size - requested size in longwords
fev - reference to the available Fifo_entry fev
mode - mode that specifies the behavior if there is no event available:
SLEEP = fall asleep until an event becomes available,
ASYNC return with an error status,
IF_REQUESTED = return only an event if it is actually requested by a consumer,
MIN_CNT = return only an event if there are at least min_cnt events available,
GREEDY = always return an event, if no is immediately available, create it on the fly (i.e. create a volatile buffer).
min_cnt - minimum number of events that must be available for the MIN_CNT access mode.
Returns:
ddcSuccess, ddcFailure if error, ddcBelowMinCnt if we are below MIN_CNT, ddcNoFreeFev if we request ASYNC mode and no free entry is available

ovirtual int req_nfev( int &nEvents, const int size[], Fifo_entry fev[], const int mode = SLEEP, const int min_cnt = 1 ) = 0
Requests an array of free buffer in the DD system. This call works as req_fev but works on an array of events. Note that the number of events can be modified by this routine. Its return value is the actual number of events received. This can be less than the number of events given if we request the events in async_mode.
Returns:
ddcSuccess, ddcFailure if error, ddcBelowMinCnt if we are below MIN_CNT, ddcNoFreeFev if we request ASYNC mode and no free entry is available. The return value reflects simply the status of the first req_fev call that was not ddcSuccess (or ddcSuccess if they were all successful).

ovirtual int ins_fev( Fifo_entry &fev ) = 0
Inserts an event into the DD pool. Insert is a put into the pool that garantees that the event is written into the INPUT fifo whereas put_fev puts it into the next available fifo. In this case consumers that are in the chain before the process will not see the event again.
NOTE: This member function is only used if a consumer also wants to act as a producer.
Parameters:
- Fifo_entry fev that characterizes the event.
Returns:
ddcSuccess, ddcFailure if error.

ovirtual int rel_fev( Fifo_entry &fev ) = 0
Releases the fev into the pool. Release is a put by a consumer in which he writes it into the INPUT fifo (and not the next available one.
NOTE: This member function is only used if a consumer wants to be sure that the fev is immediately freed and not being passed to another consumer in the system.
Returns:
ddcSuccess, ddcFailure if error.

ovirtual int get_fev( Fifo_entry &fev, const int iWait = -1, const char* fifo_name = NULL) = 0
Get an fev from the pool. Read an event from the pool.
Parameters:
fev - : reference to the returned fev
iWait - wait mode. By default we use the one of the fifo, only used if we want to override this behavior
- fifo_name specifies the fifo where we read from. By default we use the fifo that the process created/attached.
Returns:
ddcSuccess, ddcFailure if error.

ovirtual int put_fev( Fifo_entry &fev, const char* fifo_name = NULL ) = 0
Puts an event received with req_fev or put_fev back into the pool.
Parameters:
fifo_name - : specifies into which fifo we write the event. By default we use the fifo where we read from (INPUT if we made a ref_fev or our own fifo (if we are a consumer).
Returns:
ddcSuccess, ddcFailure if error.

ovirtual int get_nfev( int &nEvents, Fifo_entry fev[], const int iWait = -1, const char* fifo_name = NULL) = 0
Get an array of fev from the pool. Read an event from the pool. This routine works as get_fev with the difference that we now put an array of fev into the pool. See get_fev for details. Note: the parameter nEvents can be changed by this routine. As input parameter it is the number of events requested, as output parameter it is the actual number of events received. Normally one can get fewer events than requested if the Fifo read mode is async_mode.
Parameters:
fev - : reference to the returned fev
iWait - wait mode. By default we use the one of the fifo, only used if we want to override this behavior
- fifo_name specifies the fifo where we read from. By default we use the fifo that the process created/attached.
Returns:
ddcSuccess, ddcFailure if error.

ovirtual int put_nfev( int &nEvents, Fifo_entry fev[], const char* fifo_name = NULL ) = 0
Puts an array event received with req_fev or put_fev back into the pool. See put_fev for details.
Note that nEvent is an inout parameters. It return the number of events put into the pool successfully (and should be the same after the call if everything went fine.
Returns:
ddcSuccess, ddcFailure if error.

ovirtual int brc_fev( Fifo_entry &fev, const int nMsec_wait = 0 ) = 0
Broadcast an fev. Broadcast an fev across the DD pool. This routine decides which DD processes want to receive the broadcast in signal mode and which ones in usmail mode.

Broadcasts an fev over the whole dd system, i.e. every consumer process will get a copy. If wait_flag != 0, then waits until every consumer process has actually received the fev. The units of wait_flags are msec (i.e. wait_flag = 2 --> maximal wait of 2 ms).

There are two ways to broadcast the event:
If brc_flag == DD_BRC_SIGNAL then the event is broadcasted over the broadcast fifo. In this case it is garanteed that every process gets the fev, if several are attached to the same fifo. [Internally we duplicate the fev to the desired number and then every consumer process afterwards has his private copy, which he will eventually put back into the INPUT fifo.] If brc_flag == DD_BRC_USMAIL then the fev is simply written into the fifo of that process, regardless of the number of processes on that fifo. Obviously the second way has a much lower priority than the first one (and is therefore named after its famous brother!).

Only one process can broadcast at a time (simple locking mechanism brc_lock).

Parameters:
fev - : reference to the fev that we broadcast
nMsec_wait - timeout value in milliseconds which we wait for the signal broadcast.
Returns:
ddcSuccess, ddcFailure if error.

ovirtual int enable_events( const char* fifoname = NULL) = 0
Enables the reception of events in a fifo. A fifo is created in an IDLE mode. In order to receive the events, enable_events must be called. This allows a process to enable and disable receiving events in his fifo while it is attached to the DD system.
Parameters:
fifoname - if NULL, then the default fifo that the process created (or the last one that it created if it created several ones) is enabled.
Returns:
ddcSuccess, ddcFailure if error.

ovirtual int disable_events( const char* fifoname = NULL) = 0
Disable the reception of events in a fifo. Opposite of enable_fifo.
Parameters:
fifoname - if NULL, then the default fifo that the process created (or the last one that it created if it created several ones) is enabled.
Returns:
ddcSuccess, ddcFailure if error.

o Member functions to set/get process specific parameters

ovirtual int set_brccmd( int cmd, DD_BRCCMD_FCN cmd_fcn ) = 0
Set broadcast command. Optionally a process can execute a function whenever a broadcast event is received (e.g. at the end of a run). This memberfunctions allows to set the broadcast function for a given command.
Parameters:
cmd - integer value for the broadcast command type
pointer - to function to invoked upon broadcast command cmd
Returns:
ddcSuccess (or ddcFailure if all broadcast commands are already selected by the process).

ovirtual int set_protection( Fifo::eFifo_protection protection ) = 0
Set the protection of the fifo. Sets the protection of the default fifo of the process.
Parameters:
protection - : enum Fifo::eFifo_protection: fifo_unprotected, fifo_protected.
Returns:
ddcSuccess (or ddcFailure if the process has no fifo).

ovirtual Db* get_data_buffer() = 0
Return a pointer to the data buffer in the DD system. Note: This may become obsolete!

ovirtual dd_dcom_str* get_dcom_addr() = 0
Return a pointer to the DD registry dd_dcom. Note: This may become obsolete!

ovirtual int get_ddpid() const = 0
Return the id of the process (ie. the process id in the DD registry).

ovirtual int get_ddmpid() const = 0
Return the DD master id of the process (if the process is a master). A master is a DD process that created the DD system in the "w" mode. The DD system lives as long as there masters attached to it. The system removes itself when the last master detaches.
Returns:
Master id (>0) or -1 (if process is not a master).

ovirtual struct dd_config get_dd_config() const = 0
Return a copy of the DD configuration structure

ovirtual int set_reqcnt(const int req_cnt, const char* fifo_name = NULL) = 0
Sets the request count of a given fifo. The request count specifies how many buffers in maximum can be put into a fifo (if the fill mode of the fifo is fill_reqcnt).
Parameters:
req_cnt - how many events should be maximally in the fifo
- fifo_name, if not given we take the default fifo of the process.
Returns:
ddcSuccess (or ddcFailure if invalid fifo).

ovirtual int set_prescale(const int prescale, const char* fifo_name = NULL) = 0
Sets the prescale count of a given fifo. The prescale specifies the prescale with which buffers are put into the fifo (if the fill mode of the fifo is fill_prescale).
Parameters:
prescale - the prescale factor of the fifo
- fifo_name, if not given we take the default fifo of the process.
Returns:
ddcSuccess (or ddcFailure if invalid fifo).

ovirtual int set_brc( const int iBroadcast_mode = DD_BRC_OFF ) = 0
Sets the broadcast mode of the process.
Parameters:
DD_BRC_OFF - no broadcast
DD_BRC_SIGNAL receive broadcasts in signal mode
DD_BRC_USMAIL receive broadcasts in (unreliable) USMAIL mode. This mode is only unreliable if several processes share the fifo.

ovirtual int dd_dcom_lock() = 0
Lock the DD registry - will become private member after debugging

ovirtual int dd_dcom_unlock() = 0
Unlock the DD registry - will become private member after debugging

oinline char* get_name() const
Return the name of the DD system

oinline char* get_config_file() const
Return the name of the configuration file

ovirtual int get_nproc_att() const = 0
Return the number of processes that are currently attached to the system

ovirtual int get_process_semcnt( int &nSem, int* &piSemcnt ) = 0
Return the values of the DD system semaphores.
Parameters:
nSem - reference to the number of semaphores
piSemcnt - reference to array where the semaphore values are found. Note: the user is responsible for feeing the array after it is no longer used.

ovirtual int get_free_buffers( int &free_buffers ) const = 0
Returns the free buffers in the DD system. Free buffers are defined as the number of buffers that are currently in the INPUT fifo.

ovirtual int get_status() const = 0
Returns the global state of the DD system as given in the registry.
Returns:
DD_STATUS_UNUSED if system is not in use
DD_STATUS_OK everything ok
DD_STATUS_WAIT if we are waiting for processes (during call to member function wait4proc)
DD_STATUS_FLUSH if system is flushing
DD_STATUS_FKDUP if serious error happend - system should be removed!
DD_STATUS_EXIT if we are about to remove the system

o Miscellanous member functions

oBOOL isLocal() const
returns true of the DD is on the local host

ovirtual int sameEndianess() = 0
returns -1 if the DD pool has the same endianess as the client (0 otherwise)

ovirtual int setEventDataSwap( BOOL bValue ) = 0
By default the event data is not swapped between remote DD producers and clients. This routine allows to set the swap to the user defined value

ovoid error_invoke()
Is invoked if a serious error occured and the system should be removed. This is typically the case if the status is DD_FKDUP.

ostatic void printUnsupportedOperation( const char* operation )
Prints information about an usnupported operation in a given DD version

ostatic const char* const pccDefaultDDName
Default way for the DD system. Used if the user doesn't specify one.

ostatic const char* const pccDefaultDDFileName
Default DD tmp file.

oBOOL is_local
true if the DD system is local

ochar* name
name of the system

ochar* config_file
full pathname of the configuration file (or NULL if not specified)

ochar* dd_filename
full pathname of the project file (used for IPC resources)

ostatic const char* dd_version
Static string with the DD release name

Direct child classes:
rDD
lDD
Author:
C.Witzig
Date: Dec 5, 97
Version:
Last update Nov 18, 98

Alphabetic index HTML hierarchy of classes or Java


This page was generated with the help of DOC++.