NAME
Oorb::LogMgrTask - Log-message manager task for the oorb library
SYNOPSIS
-loorb $(ORBLIBS)
#include "oorb.h"
namespace Oorb
class LogMgrTsk
DESCRIPTION
The
LogMgrTask manages log messages for programs written with
the
Oorb(3) library. An instance of
LogMgrTask is
started automatically by the
Oorb::Master(3) object, within
the latter's
run method. Given the availability of this
object through the
Om variable, as documented in
Oorb::Master(3), log messages may be emitted throughout the
program with calls such as
Om->log()->notify( (char*) "Message" );
CONSTRUCTORS
-
LogMgrTask( void )
The LogMgrTask constructor is executed within the run
method of the Oorb::Master(3) object, thus should not normally
need to be invoked by application programmers.
METHODS
-
void run( void );
The LogMgrTask run method is invoked from within
Oorb::Master(3) and should not need to be called by
application programmers directly.
-
void cacheTaskDetails( Task* task );
-
void cacheTaskDetails( std::shared_ptr<Task*> task );
The cacheTaskDetails method caches the taskName and verbosity of a given task.
If called for an Oorb::Task(3) that is already known, cacheTaskDetails
updates the values.
-
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.
Notifications
The following routines all take a
msg variable containing the
message to emit; a
caller variable intended to contain the
name of the calling method, to be used in highly verbose output for
debugging purposes; and an
includeSyserr boolean value
indicating whether or not system error messages are to be included
in the output. All of these routines are based on the
elog(3)
family of routines, and are thus subject to the control mechanisms
(e.g. environment variables) of that family of routines. Internally,
these routines examine both the task-level verbosity setting of the
task that called them, and the program-level verbosity setting of the
enclosing program, and then emit messages if either one of those values
meets or exceeds the verbosity level of the
method in question.
Each verbosity level includes all of the lower verbosity levels
underneath it. For example, a program in
very verbose mode
will also emit all the messages classified as
notify or
verbose.
-
void notify( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a notification message. These messages are about major milestones or
extraordinary events.
These messages will be tagged with NFY to identify the logging level.
-
void verbose( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a message when in verbose mode. This mode is intended
to provide ongoing detail about what the program is doing.
These messages will be tagged with VRB to identify the logging level.
-
void vVerbose( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a message when in very verbose mode. This mode is
intended to provide diagnostic information to help resolve day-to-day
operations problems. Generally this is not intended to
be enabled for continuous use by operational programs, due to the
size of the resulting log files. If this mode is enabled, logs should
be truncated frequently, e.g. with the truncate_log(1) program.
These messages will be tagged with VVB to identify the logging level.
-
void xVerbose( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a message when in extremely verbose mode. This mode
includes voluminous information about individual packets received and written out,
used mainly for diagnostic purposes.
This mode should not be used under rtexec(1) management of
the orb2orb task. The extremely verbose mode is intended for short-term review of
messages with orb2orb launched from the command-line, perhaps via rtrun(1).
Messages from the extremely verbose mode will not be echoed to an orbserver(1).
These messages will be tagged with EXV to identify the logging level.
-
void dVerbose( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a message when in dump verbose mode. This includes all
lower-level messages and generally triggers dumps, in whatever
format is appropriate for logging and analysis, of incoming and outgoing messages, packets, configuration
blocks, and so on.
This mode should not be used under rtexec(1) management of
the orb2orb task. The dump verbose mode is intended for short-term review of
messages with orb2orb launched from the command-line, perhaps via rtrun(1).
Messages from the dump verbose mode will not be echoed to an orbserver(1).
These messages will be tagged with DMP to identify the logging level.
-
void tVerbose( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a message when in torrentially verbose mode. This mode
includes voluminous internal messages about timeouts, state changes, and all
sorts of very minor decisions and occurrences, used mainly for
diagnostic purposes. This mode should not be used under rtexec(1) management of
the orb2orb task. The torrentially verbose mode is intended for short-term review of
messages with orb2orb launched from the command-line, perhaps via rtrun(1).
Messages from the torrentially verbose mode will not be echoed to an orbserver(1).
These messages will be tagged with TVB to identify the logging level. This level of verbosity
is not likely to be of use directly by end users. It is meant to support remote diagnosis of and support for
otherwise intractable problems.
-
void Complain( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a non-fatal complaint. Generally these are for things that are wrong
and need operator intervention to diagnose and/or fix. Note that this method name is capitalized
to avoid clashing with Antelope stock.h macros.
These messages will be tagged with CPN to identify the logging level.
-
void Die( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a fatal complaint and exit the program. Note that this method name
is capitalized to avoid clashing with Antelope stock.h macros.
These messages will be tagged with DIE to identify the logging level.
-
void die_initializing( bool printUsage, std::string msg, std::string caller = , bool includeSyserr = false );
Issue a fatal complaint and exit the program, printing the usage line if
the printUsage boolean is true.
These messages will be tagged with DII to identify the logging level.
-
void DEBUG( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a debugging message. This method is intended to be used only
during program development. For users and application programmers both,
the DEBUG message level should not be construed as a one-level increase
of verbosity over the dump verbosity level. Generally all DEBUG
messages should be stripped out of production code (perhaps shifted
to a different, high verbosity level as appropriate, often to extremely verbose mode) before shipment.
These messages will be tagged with DBG to identify the logging level.
-
void SCAFFOLD( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a message indicating a part of code has been scaffolded out but not
implemented yet. This method is not intended for production code.
These messages will be tagged with SCF to identify the logging level.
-
void SCAFFOLD_FEATURE( std::string msg, std::string caller = , bool includeSyserr = false );
Issue a message indicating a part of code has been scaffolded out but not
implemented yet. Specifically, this indicates specific features such as
command-line options that may be deprecated in new versions of programs.
This method may appear in production code undergoing a multi-year
development cycle.
These messages will be tagged with SFF to identify the logging level.
-
void startMsg( void );
The startMsg method prints a startup message, including a call to the banner(3) routine,
containing the program name and process ID.
-
void finishMsg( void );
The startMsg method prints a process-finishing message containing the program name and process ID.
-
void flush( void );
The flush method prints all remaining messages in the LogMgrTask queue. This method
is intended for program finalization and may be called after the LogMgrTask thread itself has
exited and joined. The flush method is normally called from within the Oorb::Master(3)
object and is not intended for application programmers.
-
char* shifted_string( char* s );
The static method shifted_string shifts the entire input block of text right by one tab character. Specifically,
shifted_string prepends a tab character to the input string, then replaces all newline characters
with newline+tab. The method always returns a newly allocated string which must be freed
by the caller.
-
char* pf2shifted_string( Pf* pf );
The static method pf2shifted_string returns a string representation of the input parameter-file pf,
using the pf2string(3) function, however the above shifted_string method is called on the
pf2string(3) output before returning, resulting in a string that is shifted one tab character to the right for
printing. The pf2shifted_string method always returns a newly allocated string which must be freeed
by the caller.
OBJECT CONFIGURATION PARAMETERS
The
LogMgrTask object contains a public member
struct of name
m_logParams which is defined as follows:
typedef struct logParamsStruct {
char* write_to_queue;
} logParamsStruct;
-
write_to_queue
The write_to_queue parameter is intended to support LogMgrTask
output of messages to an orbserver(1) via an internal
Oorb::Queue(3).
LIBRARY
-loorb $(ORBLIBS)
ATTRIBUTES
MT-Safe
SEE ALSO
Oorb(3), Oorb::Task(3), Oorb::Master(3)
BUGS AND CAVEATS
Attempts to set the
run state of the
LogMgrTask to
false
will be ignored.
To avoid recursion loops, messages at
extremely verbose output levels and above will not be
echoed to an
orbserver(1), even if the
write_to_queue option is enabled.
AUTHOR
Kent Lindquist