[Opensrf-commits] r1811 - in trunk: include/opensrf src/libopensrf (scottmk)

[svn at svn.open-ils.org]

Author: scottmk
Date: 2009-10-10 15:19:27 -0400 (Sat, 10 Oct 2009)
New Revision: 1811

Modified:
   trunk/include/opensrf/log.h
   trunk/src/libopensrf/log.c
Log:
1. osrfLogGetXid now returns a pointer to const.  We don't want the
calling code to be able to overwrite the cached copy of the
transaction id.

2. Add doxygen-style comments to document some of the functions.

M    include/opensrf/log.h
M    src/libopensrf/log.c


Modified: trunk/include/opensrf/log.h
===================================================================
--- trunk/include/opensrf/log.h	2009-10-10 02:28:49 UTC (rev 1810)
+++ trunk/include/opensrf/log.h	2009-10-10 19:19:27 UTC (rev 1811)
@@ -1,6 +1,11 @@
 #ifndef OSRF_LOG_INCLUDED
 #define OSRF_LOG_INCLUDED
 
+/**
+	@file log.h
+	@brief Header for logging routines.
+*/
+
 #include <opensrf/utils.h>
 
 #include <syslog.h>
@@ -86,7 +91,7 @@
 void osrfLogForceXid(char* xid);
 void osrfLogMkXid( void );
 void osrfLogSetIsClient(int is);
-char* osrfLogGetXid( void );
+const char* osrfLogGetXid( void );
 
 /* sets the activity flag */
 void osrfLogSetActivityEnabled( int enabled );

Modified: trunk/src/libopensrf/log.c
===================================================================
--- trunk/src/libopensrf/log.c	2009-10-10 02:28:49 UTC (rev 1810)
+++ trunk/src/libopensrf/log.c	2009-10-10 19:19:27 UTC (rev 1811)
@@ -1,3 +1,8 @@
+/**
+	@file log.c
+	@brief Routines for logging messages.
+*/
+
 #include <opensrf/log.h>
 
 #define OSRF_NO_LOG_TYPE -1
@@ -21,6 +26,14 @@
 							const char* xid, const char* msg );
 static void _osrfLogSetXid( const char* xid );
 
+/**
+	@brief Reset certain static variables to their initial values.
+
+	Of the various static variables, we here reset only three:
+	- application name (deleted)
+	- file name of log file (deleted)
+	- log type (reset to OSRF_LOG_TYPE_STDERR)
+*/
 void osrfLogCleanup( void ) {
 	free(_osrfLogAppname);
 	_osrfLogAppname = NULL;
@@ -77,6 +90,10 @@
 		openlog(_osrfLogAppname, 0, _osrfLogFacility );
 }
 
+/**
+	@brief Store a copy of a transaction id for future use.
+	@param xid Pointer to the transaction id to be stored.
+*/
 static void _osrfLogSetXid( const char* xid ) {
    if(xid) {
       if(_osrfLogXid) free(_osrfLogXid);
@@ -84,14 +101,38 @@
    }
 }
 
+/**
+	@brief Store an empty string as the transaction id.
+*/
 void osrfLogClearXid( void ) { _osrfLogSetXid(""); }
+
+/**
+	@brief Store a transaction id, unless running as a client process.
+	@param xid Pointer to the new transaction id
+*/
 void osrfLogSetXid(char* xid) {
    if(!_osrfLogIsClient) _osrfLogSetXid(xid);
 }
+
+/**
+	@brief Store a transaction id, unconditionally, for future use.
+	@param xid Pointer to the new transaction id
+*/
 void osrfLogForceXid(char* xid) {
    _osrfLogSetXid(xid);
 }
 
+/**
+	@brief For client processes only: create and store a unique transaction id.
+
+	The generated transaction id concatenates a prefix (which must have been generated
+	previously by osrfLogSetIsClient()) and a sequence number that is incremented on each
+	call.
+
+	Since the various pieces of the transaction id are of variable length, and not separated
+	by any non-numeric characters, the result is not guaranteed to be unique.  However
+	collisions should be rare.
+*/
 void osrfLogMkXid( void ) {
    if(_osrfLogIsClient) {
       static int _osrfLogXidInc = 0; /* increments with each new xid for uniqueness */
@@ -102,10 +143,22 @@
    }
 }
 
-char* osrfLogGetXid( void ) {
+/**
+	@brief Return a pointer to the currently stored transaction id, if any.
+	@return Pointer to the currently stored transaction id.
+
+	If no transaction id has been stored, return NULL.
+*/
+const char* osrfLogGetXid( void ) {
    return _osrfLogXid;
 }
 
+/**
+	@brief Note whether the current process is a client; if so, generate a transaction prefix.
+	@param is A boolean; true means the current process is a client, false means it isn't.
+
+	The generated prefix concatenates a timestamp (the return from time()) and a process id.
+*/
 void osrfLogSetIsClient(int is) {
    _osrfLogIsClient = is;
    if(!is) return;