1 thilo.boehm 1.1 //%2006////////////////////////////////////////////////////////////////////////
  2                 //
  3                 // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
  4                 // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
  5                 // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
  6                 // IBM Corp.; EMC Corporation, The Open Group.
  7                 // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
  8                 // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
  9                 // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 10                 // EMC Corporation; VERITAS Software Corporation; The Open Group.
 11                 // Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 12                 // EMC Corporation; Symantec Corporation; The Open Group.
 13                 //
 14                 // Permission is hereby granted, free of charge, to any person obtaining a copy
 15                 // of this software and associated documentation files (the "Software"), to
 16                 // deal in the Software without restriction, including without limitation the
 17                 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 18                 // sell copies of the Software, and to permit persons to whom the Software is
 19                 // furnished to do so, subject to the following conditions:
 20                 // 
 21                 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 22 thilo.boehm 1.1 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 23                 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 24                 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 25                 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 26                 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 27                 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 28                 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 29                 //
 30                 //==============================================================================
 31                 //
 32                 //%/////////////////////////////////////////////////////////////////////////////
 33                 
 34                 
 35                 #ifndef Pegasus_TraceMemoryHandler_h
 36                 #define Pegasus_TraceMemoryHandler_h
 37                 
 38                 #include <cstdarg>
 39                 #include <cstdio>
 40                 #include <Pegasus/Common/String.h>
 41                 #include <Pegasus/Common/Linkage.h>
 42                 #include <Pegasus/Common/TraceHandler.h>
 43 thilo.boehm 1.1 #include <Pegasus/Common/TraceFileHandler.h>
 44                 #include <Pegasus/Common/Mutex.h>
 45                 #include <Pegasus/Common/AtomicInt.h>
 46                 
 47                 PEGASUS_NAMESPACE_BEGIN
 48                 
 49                 /** TraceMemoryHandler implements tracing of messages to a memory buffer
 50                  */
 51                 #define PEGASUS_TRC_DEFAULT_BUFFER_SIZE_KB 10*1024
 52                 #define PEGASUS_TRC_BUFFER_EYE_CATCHER "PEGASUSMEMTRACE"
 53                 #define PEGASUS_TRC_BUFFER_EYE_CATCHER_LEN 16
 54                 
 55                 class PEGASUS_COMMON_LINKAGE TraceMemoryHandler: public TraceHandler
 56                 {
 57                 public:
 58                 
 59                     /** Writes message with format string to the tracing facility
 60                         @param    message  message to be written
 61                         @param    msgLen   lenght of message without terminating '\0'
 62                         @param    fmt      printf style format string
 63                         @param    argList  variable argument list
 64 thilo.boehm 1.1      */
 65                     virtual void handleMessage(const char* message,
 66                                                Uint32 msgLen,
 67                                                const char* fmt,
 68                                                va_list argList);
 69                 
 70                     /** Writes simple message to the tracing facility.
 71                         @param    message  message to be written
 72                      */
 73                     virtual void handleMessage(const char* message,
 74                                                Uint32 msgLen);
 75                 
 76                     /** Validates the File Path for the trace File
 77                         @param    filePath full path of the file
 78                         @return   1        if the file path is valid
 79                                   0        if the file path is invalid
 80                      */
 81                     virtual Boolean isValidMessageDestination(const char* traceFileName);
 82                 
 83                     /** Sets the filename for the trace handler. In this implementation
 84                         we just keep the name around in case we have to flush the trace
 85 thilo.boehm 1.1         buffer later on to somewhere.
 86                         @param    destination tracer destination, e.g. file
 87                         @return   0           if the function is successful
 88                                   1           if an error occurs
 89                      */
 90                     virtual Uint32 setMessageDestination(const char* destination);
 91                 
 92                     /** Flushes the trace
 93                      */
 94                     virtual void flushTrace();
 95                 
 96                     /** Dumps the complete content of the trace buffer to a file
 97                         @param    filename  name of the file where to dump the trace buffer
 98                      */
 99                     void dumpTraceBuffer(const char* filename);
100                 
101                     /** Tells an instance of the traceMemoryHandler that it will be destructed
102                         soon and should accept no more requests for trace messages.
103                      */
104                     void die();
105                 
106 thilo.boehm 1.1     /** Constructs a TraceMemoryHandler with a default buffer size.
107                      */
108                     TraceMemoryHandler();
109                 
110                     /** Constructs a TraceMemoryHandler with a custom buffer size.
111                         @param    bufferSize  size of the trace buffer in Kbyte
112                      */
113                     TraceMemoryHandler(Uint32 bufferSize);
114                 
115                     virtual ~TraceMemoryHandler();
116                     
117                 private:
118                 
119                     /** The trace area is defined a struct to keep the following information
120                         together in memory, next the trace statementes:
121                         - eyecatcher to locate the trace buffer in a dump
122                         - the size of the trace buffer
123                         - the position after the last written trace statement
124                     */
125                     struct traceArea_t
126                     {
127 thilo.boehm 1.1         char eyeCatcher[PEGASUS_TRC_BUFFER_EYE_CATCHER_LEN];
128                         Uint32 bufferSize;
129                         Uint32 nextPos;

130 kumpf       1.2         char* traceBuffer;

131 thilo.boehm 1.1     };
132                 
133                     char* _overflowBuffer;
134                     Uint32 _overflowBufferSize;
135                     struct traceArea_t *_traceArea;
136                     Uint32 _leftBytesInBuffer;   
137                 
138                     // Members used for serialization
139                     AtomicInt _inUseCounter;
140                     AtomicInt _lockCounter;
141                     Boolean _dying;
142                 
143                     // Members used for statistics only
144                     AtomicInt _contentionCount;
145                     Uint32    _numberOfLocksObtained;
146                     
147                     // Name of a tracefile, in case we need to flush the buffer to a file
148                     char* _traceFileName;
149                     
150                     /** Request to lock the memory buffer for writing a trace message.
151                         @return 1        OK, you got the lock
152 thilo.boehm 1.1                 0        No lock was obtained, give up!!
153                     */
154                     Boolean _lockBufferAccess();
155                 
156                     /** Unlock the memory buffer when no longer used for writing.
157                     */
158                     void _unlockBufferAccess();
159                 
160                     /** Appends a fixed length message to be buffer
161                     */
162                     void _appendSimpleMessage(const char* message, Uint32 msgLen );
163                     
164                     /** Appends a marker after the last trace message in the buffer
165                     */
166                     void _appendMarker();
167                     
168                     /** Memory buffer initialization routine
169                         @param    traceAreaSize    the size of the used trace buffer
170                     */
171                     void _initialize( Uint32 traceAreaSize );
172                     
173 thilo.boehm 1.1 };
174                 
175                 PEGASUS_NAMESPACE_END
176                 
177                 #endif /* Pegasus_TraceMemoryHandler_h */