NAME
Oorb::Master - Master object for constructing programs with the oorb library
SYNOPSIS
-loorb $(ORBLIBS)
#include "oorb.h"
namespace Oorb
class Master
std::shared_ptr<ConfigMgrTask> config =
std::make_shared<ConfigMgrTask>( argc, argv );
Om = std::make_shared<Oorb::Master>( config );
DESCRIPTION
This page describes the
Master class which is used within the
Oorb(3) library to create
orb(3)-based programs.
There may only be one
Master object within a given program. This single
object controls the launching and management of all threads based on
the
Oorb::Task(3) class of tasks.
The
oorb.h file declares an external variable of name
Om as
follows:
extern std::shared_ptr<Oorb::Master> Om;
The user must instantiate this
Om object within the program.
Instantiating the object requires handing the
Master constructor
an instance of a subclass of the
Oorb::ConfigMgrTask(3). It is the job
of that configuration object to set up the
Master object such that it
runs the components necessary for the program being launched. See the
Oorb(3) man-page for a simple example.
Once the main program has instantiated the
Master object, the
main program should then call the
Master object's
run method to
start all processing.
Necessary
Oorb::Queue(3) instances are automatically generated
based on the configuration inputs of the
Oorb::OrbConnectionTask(3)
objects and do not need to be separately created by the application
programmer.
CONSTRUCTORS
-
Master( std::shared_ptr<ConfigMgrTask> config )
This Master constructor takes a shared_ptr to a subclass of the
Oorb::ConfigMgrTask, which governs what additional Oorb::Task(3)s
the Master object will launch, and how they will be configured.
The Master constructor will allow only one instance to be created in
a given program.
METHODS
-
void run( void );
The run method launches all tasks configured by the input
Oorb::ConfigMgrTask(3) (including of course the launch of the
input Oorb::ConfigMgrTask(3) itself), then processes any commands
sent to the
Master until it is requested to shut down (which also happens
via a command, usually issued by the Oorb::SignalMgrTask(3)).
The Master object also launches one each of several support
tasks including Oorb::LogMgrTask(3), Oorb::SignalMgrTask(3),
Oorb::StateMgrTask(3), Oorb::StatusMgrTask(3), and
Oorb::CommandMgrTask(3).
-
void launchTask( std::shared_ptr<Oorb::Task> task );
The launchTask method starts the input task in a new thread.
This includes creating the thread, registering it within the Master
object for future access, and invoking the run method of the input task.
Normally launchTask is called within the Master object itself, and
should be used by application programmers only for advanced
applications, such as dynamically restarting tasks during program
execution.
-
std::string getTaskName( std::thread::id tid );
The getTaskName method reports the taskName for the task running in the
thread given by the input thread-id tid.
-
void incrementVerbose( void );
The incrementVerbose method increments the verbosity of the
entire program by one step up the ladder of verbosity values as
documented in Oorb::LogMsg::Severity(3).
-
void registerTask( Task* task );
The registerTask method registers the calling task with the Master object.
This method is meant to be called from within the init_run method of
tasks based on Oorb::Task(3) and should not normally need to be invoked
by application programmers.
-
void deregisterTask( std::string taskName );
The deregisterTask method removes the registration of the calling task with
the Master object. This method is meant to be called from within the
finalize_run method of tasks based on Oorb::Task(3) and should not
normally need to be invoked by application programmers.
-
void requestProgramStop( void );
The requestProgramStop method allows any other task in an
Oorb(3)-based program to request of the Master object
that it stop the program.
-
void addOrb( std::string orbname );
The addOrb method adds the given orbname to the program's
list of orbserver(1)s to connect. Normally this method is
called from within the input Oorb::ConfigMgrTask(3).
-
void tagOrb( std::string orbname, std::string orbtag );
The tagOrb method adds an orbtag to the given orbname
within the program. An orbtag is a generic way to refer to an
orbserver(1) in configuration files etc., for example dataorb,
inputorb, outputorb, commandorb, etc.
-
void addTaggedOrb( std::string orbname, std::string orbtag );
The addOrb method adds the given orbname to the program's
list of orbserver(1)s to connect, adding a tag name via the
tagOrb method in the process. Normally this method is
called from within the input Oorb::ConfigMgrTask(3).
-
void addConnection( Pf* pf );
The addConnection method requests the launch of a read or write
connection for a program. Normally this method is called from within the
input Oorb::ConfigMgrTask(3). The addConnection takes a single
Antelope parameter-file pointer (see pf(3)) argument pf which
elaborates on details about the connection. For an explanation of this
input parameter file, see the Oorb::OrbConnection(3) man-page.
-
std::shared_ptr<Orb> getOrbByName( std::string orbname );
-
std::shared_ptr<Orb> getOrbByTag( std::string orbtag );
-
std::shared_ptr<Orb> getOrb( std::string orbtag, std::string orbname );
-
std::shared_ptr<Queue> getQueue( std::string queueName );
The methods getOrbByName, getOrbByTag, getOrb, and
getQueue retrieve a shared_ptr to an Oorb::Orb(3) or
Oorb::Queue(3) object, respectively, corresponding to the input
orbname, orbtag, or queueName. If non-empty orbtag and
orbname are both specified to getOrb, the orbname will be ignored.
-
std::shared_ptr<Task> getTask( std::string taskName );
-
std::shared_ptr<Task> getTask( std::thread::id tid );
-
std::shared_ptr<OrbConnectionTask> getConnectionTask( std::string taskName );
The getTask and getConnectionTask methods retrieve a
shared_ptr to the task given by the input taskName or thread-id
tid. The getTask method searches all Oorb::Task(3)s in the
program; getConnectionTask limits the search to orbserver(1)
read- and write-connections.
-
std::shared_ptr<CommandMgrTask> commands( void );
-
std::shared_ptr<ConfigMgrTask> config( void );
-
std::shared_ptr<LogMgrTask> log( void );
-
std::shared_ptr<SignalMgrTask> signal( void );
-
std::shared_ptr<StateMgrTask> state( void );
-
std::shared_ptr<StatusMgrTask> status( void );
These six methods return shared_ptrs to the program's supporting tasks.
Frequently they are used to issue log messages (via Om->log()), or
to configure supporting-task parameters from within the input
Oorb::ConfigMgrTask(3) run()-method implementation.
OBJECT CONFIGURATION PARAMETERS
The
Master object contains a public member
struct of name
m_masterParams which is defined as follows:
typedef struct masterParamsStruct {
double internal_timeout_sec;
double acq_starttime_program;
double acq_endtime_program;
char* match_program;
char* reject_program;
char* target_name;
LogMsg::Severity verbosity_program;
bool acknowledge_program;
} masterParamsStruct;
The
BUConfigure(3) names for these parameters are actually slightly
simplified versions, to avoid confusing end-users of programs built on the
Oorb(3) library (which, admittedly, puts directly onto the application
programmer the burden of disentangling configuration details). In particular,
the
_program suffix on many of the above variables is an attempt
to distinguish program-wide configuration settings from similarly named
settings for individual
Oorb::Task(3)s, which may override the program
settings, or vice versa.
-
internal_timeout_sec
The double-precision value internal_timout_sec is used in
a variety of places throughout the Oorb(3) library to
govern timeouts, for example on orbreap_timeout(3) calls,
spin-prevention sleeps in processing loops, etc. This parameter may not
be left null.
-
acq_starttime_program
The double-precision value acquisition_starttime_program
specifies an epoch time indicating the data timestamps at which
orb(3) acquisition should start. If not specified, this defaults
to a null value of -9999999999.999 (defined as the oorb.h macro
EPOCHTIME_NULL). In the BUConfigure(3)
configure method this parameter should be referred to by the name
acq_starttime. This parameter may be left null.
-
acq_endtime_program
The double-precision value acquisition_endtime_program
specifies an epoch time indicating the data timestamps, measured at
program launch, at which orb(3) acquisition should end.
The value may be specified as last, in which case this is set to
-8888888888.888 (defined as the oorb.h macro EPOCHTIME_LAST).
If not specified, this defaults to a null value of -9999999999.999.
In the BUConfigure(3) configure method this parameter should
be referred to by the name acq_endtime. This parameter may be left null.
-
match_program
The char* value match_program is a program-wide matching
expression given to underlying orbselect(3) calls.
In the BUConfigure(3) configure method this parameter should
be referred to by the name match. This parameter may be left null.
-
reject_program
The char* value reject_program is a program-wide matching
expression given to underlying orbreject(3) calls.
In the BUConfigure(3) configure method this parameter should
be referred to by the name reject. This parameter may be left null.
-
target_name
The char* value target_name is the name of the enclosing
program that should be used when issuing orb-based commands to the
program via utilities such as dlcmd(1). This parameter may not
be left null.
-
verbosity_program
The Oorb::LogMsg::Severity(3) value verbosity_program is a
program-wide verbosity level for messages emitted by the
Oorb::LogMgrTask(3). This value may be one of quiet, notify,
verbose, very, extremely, dump, or debug.
In the BUConfigure(3) configure method this parameter should
be referred to by the name verbose. This parameter may not be left null.
-
acknowledge_program
The bool value acknowledge_program is a program-wide instruction
for connections to use orbputx(3) instead of orbput(3) for
data writes to an orbserver(1).
In the BUConfigure(3) configure method this parameter should
be referred to by the name acknowledge. This parameter may not be left
null.
EXAMPLE
See the
Oorb(3) man-page for an example of using the
Master class.
LIBRARY
-loorb $(ORBLIBS)
ATTRIBUTES
MT-Safe
SEE ALSO
Oorb(3), Oorb::Task(3), Oorb::ConfigMgrTask(3)
BUGS AND CAVEATS
Attempts to set the
run state of the
Master to
false
will be ignored.
AUTHOR
Kent Lindquist