From 79dac398bb5c92b84456b578ce127b9bc5821c66 Mon Sep 17 00:00:00 2001
From: scottmk <scottmk@9efc2488-bf62-4759-914b-345cdb29e865>
Date: Sat, 10 Oct 2009 19:19:27 +0000
Subject: [PATCH] 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


git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@1811 9efc2488-bf62-4759-914b-345cdb29e865
---
 include/opensrf/log.h |  7 ++++++-
 src/libopensrf/log.c  | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/include/opensrf/log.h b/include/opensrf/log.h
index 8463708..63d0e05 100644
--- a/include/opensrf/log.h
+++ b/include/opensrf/log.h
@@ -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 osrfLogSetXid(char* xid);
 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 );
diff --git a/src/libopensrf/log.c b/src/libopensrf/log.c
index 514b9f0..b2d5dd3 100644
--- a/src/libopensrf/log.c
+++ b/src/libopensrf/log.c
@@ -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 @@ static void _osrfLogToFile( const char* label, long pid, const char* filename, i
 							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 @@ void osrfLogInit( int type, const char* appname, int maxlevel ) {
 		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 @@ static void _osrfLogSetXid( const char* xid ) {
    }
 }
 
+/**
+	@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 @@ void osrfLogMkXid( void ) {
    }
 }
 
-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;
-- 
2.11.0