ACE_Log_Msg Class Reference

Provides a variable length argument message logging abstraction. More...

#include <Log_Msg.h>

Collaboration diagram for ACE_Log_Msg:

Collaboration graph
[legend]
List of all members.

Public Types

enum  {
  STDERR = 1, LOGGER = 2, OSTREAM = 4, MSG_CALLBACK = 8,
  VERBOSE = 16, VERBOSE_LITE = 32, SILENT = 64, SYSLOG = 128,
  CUSTOM = 256
}
enum  MASK_TYPE { PROCESS = 0, THREAD = 1 }

Public Member Functions

 ACE_Log_Msg (void)
 Initialize logger.
 ~ACE_Log_Msg (void)
 cleanup logger.
int open (const ACE_TCHAR *prog_name, u_long options_flags=ACE_Log_Msg::STDERR, const ACE_TCHAR *logger_key=0)
 Initialize the ACE logging facility.
void set_flags (u_long f)
void clr_flags (u_long f)
u_long flags (void)
void sync (const ACE_TCHAR *program_name)
void op_status (int status)
int op_status (void)
void errnum (int)
int errnum (void)
void linenum (int)
 Set the line number where an error occurred.
int linenum (void)
 Get the line number where an error occurred.
void file (const char *)
 Set the file name where an error occurred.
const char * file (void)
 Get the file name where an error occurred.
void msg (const ACE_TCHAR *)
 Set the message that describes what type of error occurred.
const ACE_TCHARmsg (void)
 Get the message that describes what type of error occurred.
void restart (int)
int restart (void)
void msg_ostream (ACE_OSTREAM_TYPE *)
 Update the ostream without overwriting the delete_ostream_ flag.
void msg_ostream (ACE_OSTREAM_TYPE *, int delete_ostream)
ACE_OSTREAM_TYPE * msg_ostream (void) const
 Get the ostream that is used to print error messages.
ACE_Log_Msg_Callbackmsg_callback (ACE_Log_Msg_Callback *c)
ACE_Log_Msg_Callbackmsg_callback (void) const
int inc (void)
 Nesting depth increment.
int dec (void)
 Nesting depth decrement.
int trace_depth (void)
 Get trace depth.
void trace_depth (int)
 Set trace depth.
int trace_active (void)
 Set trace active status.
void trace_active (int value)
 Get trace active status.
ACE_Thread_Descriptorthr_desc (void) const
 Get the TSS thread descriptor.
void thr_desc (ACE_Thread_Descriptor *td)
void stop_tracing (void)
 Stop tracing status on a per-thread basis...
void start_tracing (void)
 Start tracing status on a per-thread basis...
int tracing_enabled (void)
 Query tracing status on a per-thread basis...
u_long priority_mask (MASK_TYPE=THREAD)
 Get the current ACE_Log_Priority mask.
u_long priority_mask (u_long, MASK_TYPE=THREAD)
 Set the ACE_Log_Priority mask, returns original mask.
int log_priority_enabled (ACE_Log_Priority log_priority)
 Return true if the requested priority is enabled.
int log_priority_enabled (ACE_Log_Priority log_priority, const char *,...)
 Return true if the requested priority is enabled.
int log_priority_enabled (ACE_Log_Priority log_priority, const wchar_t *,...)
 Return true if the requested priority is enabled.
pid_t getpid (void) const
const ACE_TCHARlocal_host (void) const
 Get the name of the local host.
void local_host (const ACE_TCHAR *)
 Set the name of the local host.
void set (const char *file, int line, int op_status=-1, int errnum=0, int restart=1, ACE_OSTREAM_TYPE *os=0, ACE_Log_Msg_Callback *c=0)
void conditional_set (const char *file, int line, int op_status, int errnum)
ssize_t log (ACE_Log_Priority priority, const char *format,...)
ssize_t log (ACE_Log_Priority priority, const wchar_t *format,...)
ssize_t log (const ACE_TCHAR *format, ACE_Log_Priority priority, va_list argp)
ssize_t log (ACE_Log_Record &log_record, int suppress_stderr=0)
int log_hexdump (ACE_Log_Priority log_priority, const char *buffer, size_t size, const ACE_TCHAR *text=0)
void dump (void) const
 Dump the state of an object.
Allow apps to acquire and release internal synchronization
lock

This lock is used internally by the ACE_Log_Msg implementation. By exporting the lock, applications can hold the lock atomically over a number of calls to ACE_Log_Msg.

int acquire (void)
 Acquire the internal lock.
int release (void)
 Release the internal lock.

Static Public Member Functions

static ACE_Log_Msginstance (void)
 Returns a pointer to the Singleton.
static int last_error_adapter (void)
 Returns last error.
static int exists (void)
 Returns non-null if an ACE_Log_Msg exists for the calling thread.
static const ACE_TCHARprogram_name (void)
 Returns the current program name used for logging.
static void disable_debug_messages (ACE_Log_Priority priority=LM_DEBUG)
static void enable_debug_messages (ACE_Log_Priority priority=LM_DEBUG)
static ACE_Log_Msg_Backendmsg_backend (ACE_Log_Msg_Backend *b)
static ACE_Log_Msg_Backendmsg_backend (void)
static void init_hook (ACE_OS_Log_Msg_Attributes &attributes)
static void inherit_hook (ACE_OS_Thread_Descriptor *thr_desc, ACE_OS_Log_Msg_Attributes &attributes)

Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks.

Private Member Functions

ACE_Log_Msgoperator= (const ACE_Log_Msg &)
 ACE_Log_Msg (const ACE_Log_Msg &)

Static Private Member Functions

static void close (void)
 For cleanup, at program termination.
static void sync_hook (const ACE_TCHAR *prg_name)
 Decouple the OS layer from the ACE_Log_Msg layer.
static ACE_OS_Thread_Descriptorthr_desc_hook (void)
 Return the TSS singleton thread descriptor.

Private Attributes

int status_
 Status of operation (-1 means failure, >= 0 means success).
int errnum_
 Type of error that occurred (see <sys/errno.h>).
int linenum_
 Line number where the error occurred.
char file_ [MAXPATHLEN+1]
 File where the error occurred.
ACE_TCHAR msg_ [ACE_MAXLOGMSGLEN+1]
int restart_
ACE_OSTREAM_TYPE * ostream_
 The ostream where logging messages can be written.
ACE_Log_Msg_Callbackmsg_callback_
 The callback object.
int trace_depth_
 Depth of the nesting for printing traces.
int trace_active_
 Are we already within an ACE_Trace constructor call?
int tracing_enabled_
 Are we allowing tracing in this thread?
int delete_ostream_
 Are we deleting this ostream?
ACE_Thread_Descriptorthr_desc_
u_long priority_mask_
int timestamp_
 Always timestamp?
struct {
   int   is_set_
   const char *   file_
   int   line_
   int   op_status_
   int   errnum_
conditional_values_

Static Private Attributes

static u_long process_priority_mask_
static const ACE_TCHARprogram_name_ = 0
 Records the program name.
static const ACE_TCHARlocal_host_ = 0
 Name of the local host (used when printing messages).
static pid_t pid_ = -1
 Process id of the current process.
static u_long flags_ = ACE_Log_Msg::STDERR
 Default is to use stderr.
static int msg_off_ = 0
 Offset of msg_[].
static int instance_count_ = 0
static u_long default_priority_mask_ = 0

Detailed Description

Provides a variable length argument message logging abstraction.

This class is very flexible since it allows formatted error messages to be printed in a thread-safe manner to various locations, such as stdout, stderr, cerr, a distributed logger, etc. The current message is also kept in a thread-specific storage location (threads spawned using ACE_Thread_Manager automatically get an ACE_Log_Msg object that inherits the spawning thread's settings), which can be used to communicate errors between framework methods and callers. A message is logged by the log() method, only if the message priority is currently enabled. Moreover, only the current log message is stored here -- it will be overwritten by the subsequent call to log().

The ACE_Log_Msg class uses two priority masks to control its logging behavior. The priority_mask_ object attribute is thread- specific and specifies the priority levels logged by the thread. The process_priority_mask_ class attribute is not thread-specific and specifies the priority levels that will be logged by all threads in the process. By default, all levels are disabled for priority_mask_ and all levels are enabled for process_priority_mask_ (i.e. the process-wide mask controls the settings, and each instance can expand on it if desired). Both priority masks can be modified using the priority_mask() method of this class.


Member Enumeration Documentation

anonymous enum
 

Enumerator:
STDERR  Write messages to stderr.
LOGGER  Write messages to the local client logger deamon.
OSTREAM  Write messages to the ostream * stored in thread-specific storage.
MSG_CALLBACK  Write messages to the callback object.
VERBOSE  Display messages in a verbose manner.
VERBOSE_LITE  Display messages in a less verbose manner (i.e., only print information that can change between calls).
SILENT  Do not print messages at all (just leave in thread-specific storage for later inspection).
SYSLOG  Write messages to the system's event log.
CUSTOM  Write messages to the user provided backend.

enum ACE_Log_Msg::MASK_TYPE
 

Enumerator:
PROCESS 
THREAD 


Constructor & Destructor Documentation

ACE_Log_Msg::ACE_Log_Msg void   ) 
 

Initialize logger.

ACE_Log_Msg::~ACE_Log_Msg void   ) 
 

cleanup logger.

ACE_Log_Msg::ACE_Log_Msg const ACE_Log_Msg  )  [private]
 


Member Function Documentation

int ACE_Log_Msg::acquire void   ) 
 

Acquire the internal lock.

void ACE_Log_Msg::close void   )  [static, private]
 

For cleanup, at program termination.

void ACE_Log_Msg::clr_flags u_long  f  ) 
 

Disable the bits in the logger's options flags.

void ACE_Log_Msg::conditional_set const char *  file,
int  line,
int  op_status,
int  errnum
 

These values are only actually set if the requested priority is enabled.

int ACE_Log_Msg::dec void   ) 
 

Nesting depth decrement.

void ACE_Log_Msg::disable_debug_messages ACE_Log_Priority  priority = LM_DEBUG  )  [static]
 

Clears the flag from the default priority mask used to initialize ACE_Log_Msg instances.

void ACE_Log_Msg::dump void   )  const
 

Dump the state of an object.

void ACE_Log_Msg::enable_debug_messages ACE_Log_Priority  priority = LM_DEBUG  )  [static]
 

Sets the flag in the default priority mask used to initialize ACE_Log_Msg instances.

int ACE_Log_Msg::errnum void   ) 
 

Get the value of the errnum (by convention this corresponds to errno).

void ACE_Log_Msg::errnum int   ) 
 

Set the value of the errnum (by convention this corresponds to errno).

int ACE_Log_Msg::exists void   )  [static]
 

Returns non-null if an ACE_Log_Msg exists for the calling thread.

const char * ACE_Log_Msg::file void   ) 
 

Get the file name where an error occurred.

void ACE_Log_Msg::file const char *   ) 
 

Set the file name where an error occurred.

u_long ACE_Log_Msg::flags void   ) 
 

Return the bits in the logger's options flags.

pid_t ACE_Log_Msg::getpid void   )  const
 

Optimize reading of the pid (avoids a system call if the value is cached...).

int ACE_Log_Msg::inc void   ) 
 

Nesting depth increment.

void ACE_Log_Msg::inherit_hook ACE_OS_Thread_Descriptor thr_desc,
ACE_OS_Log_Msg_Attributes attributes
[static]
 

Inherit hook, the attributes field is a ACE_OS_Log_Msg_Attributes object, invoke the inherit_log_msg() method on it, then destroy it and set the attribute argument to 0.

void ACE_Log_Msg::init_hook ACE_OS_Log_Msg_Attributes attributes  )  [static]
 

Parameters:
attributes  Init hook, create a Log_Msg_Attribute object, initialize its attributes from the TSS Log_Msg and save the object in the attributes argument

ACE_Log_Msg * ACE_Log_Msg::instance void   )  [static]
 

Returns a pointer to the Singleton.

int ACE_Log_Msg::last_error_adapter void   )  [static]
 

Returns last error.

int ACE_Log_Msg::linenum void   ) 
 

Get the line number where an error occurred.

void ACE_Log_Msg::linenum int   ) 
 

Set the line number where an error occurred.

void ACE_Log_Msg::local_host const ACE_TCHAR  ) 
 

Set the name of the local host.

const ACE_TCHAR * ACE_Log_Msg::local_host void   )  const
 

Get the name of the local host.

ssize_t ACE_Log_Msg::log ACE_Log_Record log_record,
int  suppress_stderr = 0
 

Log a custom built log record to the currently enabled logging sinks.

ssize_t ACE_Log_Msg::log const ACE_TCHAR format,
ACE_Log_Priority  priority,
va_list  argp
 

An alternative logging mechanism that makes it possible to integrate variable argument lists from other logging mechanisms into the ACE mechanism.

ssize_t ACE_Log_Msg::log ACE_Log_Priority  log_priority,
const wchar_t *  format_str,
  ...
 

Since this is the ANTI_TCHAR version, we need to convert the format string over.

ssize_t ACE_Log_Msg::log ACE_Log_Priority  priority,
const char *  format,
  ...
 

Format a message to the thread-safe ACE logging mechanism. Valid options (prefixed by '', as in printf format strings) include:

  • 'A': print an ACE_timer_t value (which could be either double or ACE_UINT32.)
  • 'a': abort the program at this point abruptly.
  • 'c': print a character
  • 'C': print a character string
  • 'i', 'd': print a decimal number
  • 'I': indent according to nesting depth (obtained from ACE_Trace::get_nesting_indent()).
  • 'e', 'E', 'f', 'F', 'g', 'G': print a double
  • 'l': print line number where an error occurred.
  • 'M': print the name of the priority of the message.
  • 'm': return the message corresponding to errno value, e.g., as done by strerror()
  • 'N': print file name where the error occurred.
  • 'n': print the name of the program (or "<unknown>" if not set)
  • 'o': print as an octal number
  • 'P': print out the current process id
  • 'p': print out the appropriate errno message from sys_errlist, e.g., as done by perror()
  • 'Q': print out the uint64 number
  • '@': print a void* pointer (in hexadecimal)
  • 'r': call the function pointed to by the corresponding argument
  • 'R': print return status
  • 'S': print out the appropriate _sys_siglist entry corresponding to var-argument.
  • 's': print out a character string
  • 'T': print timestamp in hour:minute:sec:usec format.
  • 'D': print timestamp in month/day/year hour:minute:sec:usec format.
  • 't': print thread id (1 if single-threaded)
  • 'u': print as unsigned int
  • 'w': prints a wide character
  • 'W': print a wide character string
  • 'x': print as a hex number
  • 'X': print as a hex number
  • 'z': print an ACE_OS::WChar character
  • 'Z': print an ACE_OS::WChar character string
  • '': print out a single percent sign, ''

int ACE_Log_Msg::log_hexdump ACE_Log_Priority  log_priority,
const char *  buffer,
size_t  size,
const ACE_TCHAR text = 0
 

Method to log hex dump. This is useful for debugging. Calls log() to do the actual print, but formats first to make the chars printable.

int ACE_Log_Msg::log_priority_enabled ACE_Log_Priority  log_priority,
const wchar_t *  ,
  ...
 

Return true if the requested priority is enabled.

int ACE_Log_Msg::log_priority_enabled ACE_Log_Priority  log_priority,
const char *  ,
  ...
 

Return true if the requested priority is enabled.

int ACE_Log_Msg::log_priority_enabled ACE_Log_Priority  log_priority  ) 
 

Return true if the requested priority is enabled.

const ACE_TCHAR * ACE_Log_Msg::msg void   ) 
 

Get the message that describes what type of error occurred.

void ACE_Log_Msg::msg const ACE_TCHAR  ) 
 

Set the message that describes what type of error occurred.

ACE_Log_Msg_Backend * ACE_Log_Msg::msg_backend void   )  [static]
 

ACE_Log_Msg_Backend * ACE_Log_Msg::msg_backend ACE_Log_Msg_Backend b  )  [static]
 

Set a new backend object and return the existing backend to allow "chaining". Note that as opposed to ACE_Log_Msg_Callback, ACE_Log_Msg_Backend is a per-process entity.

Note: Be aware that because of the current architecture there is no guarantee that open (), reset () and close () will be called on a backend object.

ACE_Log_Msg_Callback * ACE_Log_Msg::msg_callback void   )  const
 

ACE_Log_Msg_Callback * ACE_Log_Msg::msg_callback ACE_Log_Msg_Callback c  ) 
 

Set a new callback object and return the existing callback to allow "chaining". Note that ACE_Log_Msg_Callback objects are not inherited when spawning a new thread, so you'll need to reset them in each thread.

ACE_OSTREAM_TYPE * ACE_Log_Msg::msg_ostream void   )  const
 

Get the ostream that is used to print error messages.

void ACE_Log_Msg::msg_ostream ACE_OSTREAM_TYPE *  ,
int  delete_ostream
 

delete_stream == 1, forces Log_Msg.h to delete the stream in its own ~dtor (assumes control of the stream) use only with proper ostream (eg: fstream), not (cout, cerr)

void ACE_Log_Msg::msg_ostream ACE_OSTREAM_TYPE *   ) 
 

Update the ostream without overwriting the delete_ostream_ flag.

int ACE_Log_Msg::op_status void   ) 
 

Get the result of the operation status (by convention, -1 means error).

void ACE_Log_Msg::op_status int  status  ) 
 

Set the result of the operation status (by convention, -1 means error).

int ACE_Log_Msg::open const ACE_TCHAR prog_name,
u_long  options_flags = ACE_Log_Msg::STDERR,
const ACE_TCHAR logger_key = 0
 

Initialize the ACE logging facility.

Initialize the ACE logging facility. Supplies the program name that is available to each logging message call. Default arguments set up logging to STDERR only.

Parameters:
prog_name The name of the calling program.
options_flags A bitwise-or of options flags used to set the initial behavior and logging sink(s). (see the enum above for the valid values).
logger_key The name of ACE_FIFO rendezvous point where the local client logger daemon is listening for logging messages. Only meaningful if the LOGGER bit is set in the flags argument.

ACE_Log_Msg& ACE_Log_Msg::operator= const ACE_Log_Msg  )  [private]
 

u_long ACE_Log_Msg::priority_mask u_long  ,
MASK_TYPE  = THREAD
 

Set the ACE_Log_Priority mask, returns original mask.

u_long ACE_Log_Msg::priority_mask MASK_TYPE  = THREAD  ) 
 

Get the current ACE_Log_Priority mask.

const ACE_TCHAR * ACE_Log_Msg::program_name void   )  [static]
 

Returns the current program name used for logging.

int ACE_Log_Msg::release void   ) 
 

Release the internal lock.

int ACE_Log_Msg::restart void   ) 
 

Get the field that indicates whether interrupted calls should be restarted.

void ACE_Log_Msg::restart int   ) 
 

Set the field that indicates whether interrupted calls should be restarted.

void ACE_Log_Msg::set const char *  file,
int  line,
int  op_status = -1,
int  errnum = 0,
int  restart = 1,
ACE_OSTREAM_TYPE *  os = 0,
ACE_Log_Msg_Callback c = 0
 

Set the line number, file name, operational status, error number, restart flag, ostream, and the callback object. This combines all the other set methods into a single method.

void ACE_Log_Msg::set_flags u_long  f  ) 
 

Enable the bits in the logger's options flags.

void ACE_Log_Msg::start_tracing void   ) 
 

Start tracing status on a per-thread basis...

void ACE_Log_Msg::stop_tracing void   ) 
 

Stop tracing status on a per-thread basis...

void ACE_Log_Msg::sync const ACE_TCHAR program_name  ) 
 

Call after doing a fork() to resynchronize the process id and program_name_ variables.

void ACE_Log_Msg::sync_hook const ACE_TCHAR prg_name  )  [static, private]
 

Decouple the OS layer from the ACE_Log_Msg layer.

void ACE_Log_Msg::thr_desc ACE_Thread_Descriptor td  ) 
 

Set the TSS thread descriptor. This method will call td->acquire_release to block execution until this call return.

ACE_Thread_Descriptor * ACE_Log_Msg::thr_desc void   )  const
 

Get the TSS thread descriptor.

ACE_OS_Thread_Descriptor * ACE_Log_Msg::thr_desc_hook void   )  [static, private]
 

Return the TSS singleton thread descriptor.

void ACE_Log_Msg::trace_active int  value  ) 
 

Get trace active status.

int ACE_Log_Msg::trace_active void   ) 
 

Set trace active status.

void ACE_Log_Msg::trace_depth int   ) 
 

Set trace depth.

int ACE_Log_Msg::trace_depth void   ) 
 

Get trace depth.

int ACE_Log_Msg::tracing_enabled void   ) 
 

Query tracing status on a per-thread basis...


Member Data Documentation

ACE_Log_Msg::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

struct { ... } ACE_Log_Msg::conditional_values_ [private]
 

Anonymous struct since there will only be one instance. This struct keeps information stored away in case we actually end up calling log() if the log priority is correct.

u_long ACE_Log_Msg::default_priority_mask_ = 0 [static, private]
 

Priority mask to use for each new instance

int ACE_Log_Msg::delete_ostream_ [private]
 

Are we deleting this ostream?

int ACE_Log_Msg::errnum_ [private]
 

Type of error that occurred (see <sys/errno.h>).

const char* ACE_Log_Msg::file_ [private]
 

char ACE_Log_Msg::file_[MAXPATHLEN+1] [private]
 

File where the error occurred.

u_long ACE_Log_Msg::flags_ = ACE_Log_Msg::STDERR [static, private]
 

Default is to use stderr.

Options flags used to hold the logger flag options, e.g., STDERR, LOGGER, OSTREAM, MSG_CALLBACK, etc.

int ACE_Log_Msg::instance_count_ = 0 [static, private]
 

Number of existing ACE_Log_Msg instances; when 0, delete program/host names

int ACE_Log_Msg::is_set_ [private]
 

int ACE_Log_Msg::line_ [private]
 

int ACE_Log_Msg::linenum_ [private]
 

Line number where the error occurred.

const ACE_TCHAR * ACE_Log_Msg::local_host_ = 0 [static, private]
 

Name of the local host (used when printing messages).

ACE_TCHAR ACE_Log_Msg::msg_[ACE_MAXLOGMSGLEN+1] [private]
 

The log message, which resides in thread-specific storage. Note that only the current log message is stored here -- it will be overwritten by the subsequent call to log().

ACE_Log_Msg_Callback* ACE_Log_Msg::msg_callback_ [private]
 

The callback object.

int ACE_Log_Msg::msg_off_ = 0 [static, private]
 

Offset of msg_[].

int ACE_Log_Msg::op_status_ [private]
 

ACE_OSTREAM_TYPE* ACE_Log_Msg::ostream_ [private]
 

The ostream where logging messages can be written.

pid_t ACE_Log_Msg::pid_ = -1 [static, private]
 

Process id of the current process.

u_long ACE_Log_Msg::priority_mask_ [private]
 

Keeps track of all the per-thread ACE_Log_Priority values that are currently enabled. Default is for all logging priorities to be disabled.

u_long ACE_Log_Msg::process_priority_mask_ [static, private]
 

Initial value:

Keeps track of all the per-process ACE_Log_Priority values that are currently enabled. Default is for all logging priorities to be enabled.

const ACE_TCHAR * ACE_Log_Msg::program_name_ = 0 [static, private]
 

Records the program name.

int ACE_Log_Msg::restart_ [private]
 

Indicates whether we should restart system calls that are interrupted.

int ACE_Log_Msg::status_ [private]
 

Status of operation (-1 means failure, >= 0 means success).

ACE_Thread_Descriptor* ACE_Log_Msg::thr_desc_ [private]
 

If we're running in the context of an ACE_Thread_Manager this will point to the thread descriptor adapter which holds the thread descriptor of the thread. This can be used to repidly access all thread data kept in ACE_Thread_Descriptor.

int ACE_Log_Msg::timestamp_ [private]
 

Always timestamp?

int ACE_Log_Msg::trace_active_ [private]
 

Are we already within an ACE_Trace constructor call?

int ACE_Log_Msg::trace_depth_ [private]
 

Depth of the nesting for printing traces.

int ACE_Log_Msg::tracing_enabled_ [private]
 

Are we allowing tracing in this thread?


The documentation for this class was generated from the following files:
Generated on Wed Nov 23 15:49:03 2005 for ACE by  doxygen 1.4.5