FARGOS/VISTA Object Management Environment Core
..
|
Implements multi-threaded, deferred physical I/O log file manager. More...
#include <logging_api.hpp>
Classes | |
class | FileNameCacheEntry |
Class to maintain fileName->shortened replacement record. More... | |
Public Types | |
enum | { MAX_LOG_LINE_LENGTH =((16 * 4096) + (3 * 64)) } |
typedef void(* | TimeAcquisitionFP) (struct timespec *, const LogManager *) |
Public Member Functions | |
void | killProcessingThread () |
uint_fast32_t | getLogPrefixMask () const OME_ALWAYS_INLINE |
Get current log prefix mask. It will be a combination of bits composed from LogMessageRecord::LogPrefixMask enums. More... | |
uint_fast32_t | setLogPrefixMask (uint_fast32_t newMask) OME_ALWAYS_INLINE |
Set the log prefix mask. The new mask is defined as a combination of bits created by OR'ing together values from the LogMessageRecord::LogPrefixMask enum. More... | |
void | setStripLeadingDirectories (uint_fast32_t dirCount) |
BufferRegion * | getBufferManager () const OME_ALWAYS_INLINE |
Provide access to the underlying BufferRegion. More... | |
IO_Processor * | get_IO_Manager () const OME_ALWAYS_INLINE |
Provide access to underlying IO_Processor. More... | |
LogManager (SharedMemoryVariableNode *parentNode, OS_HANDLE_TYPE output_fd, uint_fast8_t useSeparateThread, const char *appName, uint_fast32_t logLinePrefixMask=~0U, uint_fast32_t maxLineSize=(LogManager::MAX_LOG_LINE_LENGTH - sizeof(SharedBufferAllocRecord)), unsigned char *region=nullptr, size_t bytes=(LogManager::MAX_LOG_LINE_LENGTH *64)) | |
Create anonymous buffer. More... | |
virtual | ~LogManager () |
int | closeLog () |
Close the open log file. More... | |
SharedBufferAllocRecord * | allocateBuffer () OME_ALWAYS_INLINE |
Allocate a buffer for a log record. More... | |
void | returnBuffer (SharedBufferAllocRecord *rec) OME_ALWAYS_INLINE |
Return a buffer previously allocated by allocateBuffer(). More... | |
unsigned char * | bufferAddress (SharedBufferAllocRecord *rec, size_t *bufferLen=nullptr) const OME_ALWAYS_INLINE |
Obtain the physical address and length of a buffer from a SharedBufferAllocRecord, which are data structures intended for use in shared memory segments and utilize relative offsets, enabling simultaneous use by distinct processes that have a segment mapped to different address regions. More... | |
ssize_t | writeDataToBuffer (SharedBufferAllocRecord *rec) |
Low-level routine to add a record to log buffer. More... | |
ssize_t | copyAndWriteDataToBuffer (SharedBufferAllocRecord *rec, const void *data, size_t len) |
Low-level routine to copy data and add a record to log buffer. More... | |
ssize_t | copyAndWriteData (const void *data, size_t len) |
Write block of data to the log buffer. More... | |
const TextBlock_struct | pruneDirectoryPrefix (const char *fileName, const int_fast32_t fileNameLen) |
Return the source file name pruned of any leading directory components as indicated by settings imposed by setStripLeadingDirectories() and the stripFilePrefix table. More... | |
const char * | getErrorCondition () const OME_ALWAYS_INLINE |
Return error condition text detected. This is normally used to obtain an explanation of errors reported by the operating system when attempting to write log records. More... | |
void | setErrorCondition (const char *messageText) OME_ALWAYS_INLINE |
Set error condition text. More... | |
void | setTimeAcquisitionRoutine (TimeAcquisitionFP routine) |
Set alternate timestamp acquisition routine. More... | |
TimeAcquisitionFP | getTimeAcquisitionRoutine () const OME_ALWAYS_INLINE |
Return pointer to the time acquistion routine associated with the log. More... | |
void | getTimestamp (struct timespec *timestamp) const OME_ALWAYS_INLINE |
Return the current time using the timestamp acquisition routine associated with the log. More... | |
Static Public Member Functions | |
static void | defaultGetTime (struct timespec *timestamp, const LogManager *logMgr) |
static uint_fast32_t | addLogComponent (const char *componentName, LogMaskType_t *maskLocation, LogMaskPrimitiveType_t initialMask=0) |
Add definition of new log component. More... | |
static int | initializeLogSubsystem (int *newArgc, const char **newArgv, const int argc, const char *argv[], const char *componentName=nullptr, LogMaskType_t *appMaskLocation=nullptr, const uint_fast32_t maxLines=128, const LogMaskPrimitiveType_t logPrefixMask=~0U) |
Initialize logging-specific parameters by passing command line arguments. More... | |
static LogManager * | newLogToFileDescriptor (SharedMemoryVariableNode *parentNode, OS_HANDLE_TYPE fd, LogMaskPrimitiveType_t logPrefixMask, uint_fast8_t useSeparateThreads, unsigned char *region, size_t bytes) |
static LogManager * | newLogFileForComponent (SharedMemoryVariableNode *parentNode, const char *app, uint_fast32_t filenameCreateFlags, LogMaskPrimitiveType_t logPrefixMask, uint_fast8_t enableMap, uint_fast8_t useSeparateThreads, size_t desiredRegionSize=0, size_t reserveAtEnd=0, const char *inDir=getenv(DEFAULT_LOG_DIRECTORY_ENVIRONMENT_VARIABLE)) |
Create a new file and LogManager for a component. If desired, also create an auxilary backing file for the buffer and create a background thread to perform the actual output. More... | |
static LogManager * | newStandardLogFile (const char *namedComponent=nullptr, LogMaskPrimitiveType_t filenameCreateFlags=~0U, SharedMemoryVariableNode *parentNode=nullptr) |
High-level routine to create a standard log file associated with a component. More... | |
static int | commitLogRecord (SharedBufferAllocRecord *rec, IO_Processor *controller) |
IO_processor-compatible process routine used to write buffered data to an open file. More... | |
static void | setSourceForCustomLogTime (POSIXtimeInNanoseconds *timeSource) |
Convenience routine to set location of a custom time value for log lines. More... | |
static void | returnCustomLogTime (struct timespec *timestamp, const LogManager *logMgr) |
Convenience routine to retrieve a custom timestamp for log lines. More... | |
Public Attributes | |
TimePointCache | logTimePointCache |
TimePointCacheTable | argTimeCacheTable |
char | logFileName [256] |
Static Public Attributes | |
static LogManager * | DEFAULT_LogManager |
Default log manager used, set by newStandardLogFile() More... | |
static LogManager * | STDOUT_LogManager = &realize_STDOUT_Manager |
Created automatically. More... | |
static LogManager * | STDERR_LogManager = &realize_STDERR_Manager |
Created automatically. More... | |
Protected Types | |
enum | { MAX_FILE_PREFIX_ENTRIES = 8, FILENAME_CACHE_SIZE = 4 } |
Static Protected Member Functions | |
static void | initializePrefixTable () |
Initializes the file name prefix tables. More... | |
Protected Attributes | |
BufferRegion * | bfrMgr |
IO_Processor * | ioMgr |
const char * | errorCondition |
size_t | blockSize |
uint_fast32_t | logPrefixMask |
uint32_t | stripLeadingDirectories |
uint32_t | _explicitAlignmentPaddding |
uint32_t | cachedFileNameCount |
TimeAcquisitionFP | getTimestampRoutine |
FileNameCacheEntry | fileNameReplacementCache [FILENAME_CACHE_SIZE] |
Static Protected Attributes | |
static uint16_t | filePrefixLen [MAX_FILE_PREFIX_ENTRIES] |
static uint16_t | filePrefix2Len [MAX_FILE_PREFIX_ENTRIES] |
static const char * | stripFilePrefix [MAX_FILE_PREFIX_ENTRIES] |
static const char * | stripFilePrefix2 [MAX_FILE_PREFIX_ENTRIES] |
Private Member Functions | |
FileNameCacheEntry | findCachedFileName (const char *fileName) const |
void | addCachedFileName (const char *fileNameKey, const TextBlock_struct entry) |
Implements multi-threaded, deferred physical I/O log file manager.
typedef void(* LogManager::TimeAcquisitionFP) (struct timespec *, const LogManager *) |
|
protected |
LogManager::LogManager | ( | SharedMemoryVariableNode * | parentNode, |
OS_HANDLE_TYPE | output_fd, | ||
uint_fast8_t | useSeparateThread, | ||
const char * | appName, | ||
uint_fast32_t | logLinePrefixMask = ~0U , |
||
uint_fast32_t | maxLineSize = (LogManager::MAX_LOG_LINE_LENGTH - sizeof(SharedBufferAllocRecord)) , |
||
unsigned char * | region = nullptr , |
||
size_t | bytes = (LogManager::MAX_LOG_LINE_LENGTH * 64) |
||
) |
Create anonymous buffer.
parentNode | is a shared memory naming node under which the statistics will be rooted. |
output_fd | defines open descriptor associated with output file. |
useSeparateThread | is a Boolean flag indicating if transfer to the log file should be performed by directly by the thread writing data to the log or if should be handled by background thread. |
appName | identifies the application tag associated with messages emitted to the log. |
logLinePrefixMask | specifies the default bit mask for enabled output fields (e.g., time, thread id, file name, line number, etc.). |
maxLineSize | identifies the maximum possible output records that can be buffered before an attempt to write additional data to the log will block. |
region | is a pointer to a pre-allocated buffer, which could be a memory-mapped region. If a null pointer is passed, a buffer will be dynamically allocated. |
bytes | indicates the size of the buffer. If pre-allocated, then bytes specifies the amount of space usable in the pre-allocated buffer; otherwise it indicates the amount of space to be dynamically allocated. |
References _INVALID_DESCRIPTOR, bfrMgr, blockSize, commitLogRecord(), defaultGetTime(), getTimestampRoutine, ioMgr, LOGFILE_BFR_MAGIC_NUMBER, logPrefixMask, BufferRegion::NOT_OWNER, OME_EXPECT_TRUE, BufferRegion::OWN_BLOCK, IO_Processor::PROCESS_DURING_READ, IO_Processor::PROCESS_THREAD, BufferRegion::setOwnership(), and IO_Processor::waitForThreadStart().
Referenced by newLogToFileDescriptor().
|
virtual |
|
private |
Referenced by pruneDirectoryPrefix().
|
static |
Add definition of new log component.
componentName | identifies the component |
maskLocation | points to the memory location which will maintain the log mask. |
initialMask | specifies the initial log mask for the component. |
+logmask
command arguments and then removing any levels specified by a -logmask
command line arguments. Referenced by AutoRegisterLogComponent::AutoRegisterLogComponent(), and initializeLogSubsystem().
|
inline |
Allocate a buffer for a log record.
The SharedBufferAllocRecord describing the buffer is returned. These records are special in that they can be used with shared memory segments and use relative offsets rather than physical addresses.
References BufferRegion::allocateBlock(), bfrMgr, and blockSize.
Referenced by LogMessageRecord::formatRecordAsText(), and LogMessageRecord::prepareBinaryRecord().
|
inline |
Obtain the physical address and length of a buffer from a SharedBufferAllocRecord, which are data structures intended for use in shared memory segments and utilize relative offsets, enabling simultaneous use by distinct processes that have a segment mapped to different address regions.
rec | specifies the buffer. | |
[out] | bufferLen | is an optional argument that points at a location into which the length of the buffer will be stored. |
References bfrMgr, BufferRegion::blockAddress(), IO_Processor::bufferAddress(), ioMgr, OME_EXPECT_TRUE, and SharedBufferAllocRecord_32::usedLen.
Referenced by LogMessageRecord::formatRecordAsText(), and LogMessageRecord::prepareBinaryRecord().
int LogManager::closeLog | ( | ) |
Close the open log file.
References copyAndWriteData(), IO_Processor::currentThreadState, IO_Processor::descriptor, INVALID_HANDLE_VALUE, ioMgr, IO_Processor::PROCESS_THREAD, and IO_Processor::waitForThreadExit().
|
static |
IO_processor-compatible process routine used to write buffered data to an open file.
rec | points at the buffer to be output. |
controller | points at the IO_Processor driving the output processing. |
References IO_Processor::bufferAddress(), IO_Processor::descriptor, and waitForBufferAllocRecordToBeReady().
Referenced by LogManager().
|
inline |
Write block of data to the log buffer.
data | points to the block of data to be copied into the buffer. |
len | indicates the number of bytes to be copied. |
When this routine returns, the referenced memory block has been copied and it can be reused.
References BufferRegion::allocateBlock(), bfrMgr, and copyAndWriteDataToBuffer().
Referenced by closeLog().
ssize_t LogManager::copyAndWriteDataToBuffer | ( | SharedBufferAllocRecord * | rec, |
const void * | data, | ||
size_t | len | ||
) |
Low-level routine to copy data and add a record to log buffer.
rec | points at the allocation record for the buffer. |
data | points to the block of data to be copied into the buffer. |
len | indicates the number of bytes to be copied. |
References bfrMgr, BufferRegion::blockAddress(), SharedBufferAllocRecord_32::blockLen, OME_EXPECT_FALSE, OME_PREFETCH, SharedBufferAllocRecord_32::usedLen, and writeDataToBuffer().
Referenced by copyAndWriteData().
|
inlinestatic |
References interpolated_clock_gettime().
Referenced by LogManager(), and setTimeAcquisitionRoutine().
|
private |
Referenced by pruneDirectoryPrefix().
|
inline |
Provide access to underlying IO_Processor.
References ioMgr.
Referenced by LogMessageRecord::writeAsBinaryToBuffer(), and LogMessageRecord::writeAsTextToBuffer().
|
inline |
Provide access to the underlying BufferRegion.
References bfrMgr.
|
inline |
Return error condition text detected. This is normally used to obtain an explanation of errors reported by the operating system when attempting to write log records.
References errorCondition.
|
inline |
Get current log prefix mask. It will be a combination of bits composed from LogMessageRecord::LogPrefixMask enums.
References logPrefixMask.
Referenced by LogMessageRecord::splitLongLogLine().
|
inline |
Return pointer to the time acquistion routine associated with the log.
References getTimestampRoutine.
|
inline |
Return the current time using the timestamp acquisition routine associated with the log.
timestamp | points to the timespec structure into which the current time will be stored. |
Referenced by LogMessageRecord::LogMessageRecord().
|
static |
Initialize logging-specific parameters by passing command line arguments.
newArgc | is a pointer to a location into which a new argc value will be placed. |
newArgv | is a pointer to an array of const char pointers that will be set to a subset of the argv array after any logging-related arguments have been removed. |
argc | is a count of the arguments in argv array |
argv | is an array of const char pointers that provide command line arguments. |
componentName | is an optional argument which identifies the application or component name. If not provided, the application name is obtained from argv[0]. |
appMaskLocation | is an optional argument that points to the memory location which will hold the log mask for the application. If provided, it overrides the always-defined "app" log level mask and references to the component's active log Level mask are aliased to be the same entity as that for "app". |
maxLines | indicates maximum number of unwritten log lines to be able to buffer. The larger the value, the more output lines that can be queued up at the cost of a greater amount of permanently allocated storage. If multithreaded mode is not used, a very small value, like 1, is viable. |
logPrefixMask | is an optional argument that specifies the log line output fields that should be output for each log line. It defaults to all fields. The LogMessageRecord::LogPrefixMask enum defines the bits of interest. |
The LogMessageRecord::process_commandline_log_flags() routine is invoked to strip any logging-related arguments from command line argument list and generate a new argc and argv[].
References addLogComponent(), default_LogSubsystemInfo, LogSubsystemInfo::defaultLogPrefix, logPrefixMask, LogSubsystemInfo::maxPendingLogLines, OME_EXPECT_TRUE, LogMessageRecord::process_commandline_log_flags(), LogSubsystemInfo::processID, and LogSubsystemInfo::programName.
|
staticprotected |
Initializes the file name prefix tables.
Called once, either by initializeLogSubsystem(), but usually by the LogManager() constructor via the static constructors that create the STDOUT_LogManager and STDERR_LogManager objects.
|
inline |
References ioMgr, IO_Processor::PROCESS_THREAD, and IO_Processor::stopThread().
|
static |
Create a new file and LogManager for a component. If desired, also create an auxilary backing file for the buffer and create a background thread to perform the actual output.
parentNode | |
app | specifies the application's name |
filenameCreateFlags | |
logPrefixMask | specifies the default bit mask for enabled output fields (e.g., time, thread id, file name, line number, etc.). |
enableMap | is a Boolean flag indicating if the in-progress work buffer should be maintained in an auxillary memory-mapped file, which allows the in-progress work to be recovered if the process crashes. |
useSeparateThreads | is a Boolean flag that selects use of a separate output thread. By default, the thread that submits a log message is used to make the eventual kernel call to output the data, which can cause it to be blocked waiting for output to complete. Using a separate output thread allows a thread to submit a log line and continue working while the output thread works on processing the submitted work in the background. |
desiredRegionSize | specifies how large the memory-mapped auxillary file should be. |
reserveAtEnd | specifies the amount at the end of the region which should be left untouched. |
inDir | specifies the directory into which the log file should be created. |
References default_LogSubsystemInfo, fd, MAX_LOG_LINE_LENGTH, LogSubsystemInfo::maxPendingLogLines, OS_HANDLE_TYPE, and stderr.
|
static |
References default_LogSubsystemInfo, fd, LogManager(), logPrefixMask, MAX_LOG_LINE_LENGTH, and LogSubsystemInfo::programName.
|
static |
High-level routine to create a standard log file associated with a component.
namedComponent | specifies the application name; if not specified, it will be obtained from the process name provided to initializeLogSubsystem(). |
filenameCreateFlags | specifies the elements used to compose the log file's name. |
parentNode | specifies the node under which the shared memory variables associated with the LogManager should be parented. |
References default_LogSubsystemInfo, and LogSubsystemInfo::programName.
const TextBlock_struct LogManager::pruneDirectoryPrefix | ( | const char * | fileName, |
const int_fast32_t | fileNameLen | ||
) |
Return the source file name pruned of any leading directory components as indicated by settings imposed by setStripLeadingDirectories() and the stripFilePrefix table.
References addCachedFileName(), LogManager::FileNameCacheEntry::fileName, filePrefix2Len, filePrefixLen, findCachedFileName(), OME_EXPECT_FALSE, OME_EXPECT_TRUE, LogManager::FileNameCacheEntry::replacementText, stripFilePrefix, stripFilePrefix2, and stripLeadingDirectories.
Referenced by LogMessageRecord::formatRecordAsText(), and LogMessageRecord::prepareBinaryRecord().
|
inline |
Return a buffer previously allocated by allocateBuffer().
rec | points at the buffer to be returned. |
References bfrMgr, and BufferRegion::returnBlock().
|
static |
Convenience routine to retrieve a custom timestamp for log lines.
timestamp | points to the structure into which the current log line time will be stored. |
logMgr | references the LogManager for the log file being processed. It is ignored in this implementation, as it only supports a single time source. |
|
inline |
Set error condition text.
References errorCondition.
|
inline |
Set the log prefix mask. The new mask is defined as a combination of bits created by OR'ing together values from the LogMessageRecord::LogPrefixMask enum.
NOTE: normally the log prefix mask is set at creation time and never touched, thus all log lines would have an identical prefix format. In some rare circumstances, this may not be desirable, such as a multi-line dump of a buffer's contents.
References logPrefixMask.
|
static |
Convenience routine to set location of a custom time value for log lines.
timeSource | points to the memory location in which the current log line time will be maintained. |
Under normal usage scenarios, a call to setTimeAquisitionRoutine(LogManager::returnCustomLogTime) should subsequently be made on the relevant LogManager objects.
|
inline |
References stripLeadingDirectories.
|
inline |
Set alternate timestamp acquisition routine.
routine | is the entry point of the function. If a null pointer is provided, the defaultGetTime() routine is used. |
References defaultGetTime(), and getTimestampRoutine.
ssize_t LogManager::writeDataToBuffer | ( | SharedBufferAllocRecord * | rec | ) |
Low-level routine to add a record to log buffer.
rec | points at the allocation record for the buffer. |
References IO_Processor_Statistics::bytesRead, ioMgr, IO_Processor::statistics, IO_Processor::submitOrProcessBlock(), and SharedBufferAllocRecord_32::usedLen.
Referenced by copyAndWriteDataToBuffer(), LogMessageRecord::writeAsBinaryToBuffer(), and LogMessageRecord::writeAsTextToBuffer().
|
protected |
TimePointCacheTable LogManager::argTimeCacheTable |
Referenced by LogMessageRecord::formatRecordAsText().
|
protected |
|
protected |
Referenced by allocateBuffer(), and LogManager().
|
protected |
|
static |
|
protected |
Referenced by getErrorCondition(), and setErrorCondition().
|
protected |
|
staticprotected |
Referenced by pruneDirectoryPrefix().
|
staticprotected |
Referenced by pruneDirectoryPrefix().
|
protected |
Referenced by getTimeAcquisitionRoutine(), LogManager(), and setTimeAcquisitionRoutine().
|
protected |
char LogManager::logFileName[256] |
|
protected |
Referenced by getLogPrefixMask(), initializeLogSubsystem(), LogManager(), newLogToFileDescriptor(), and setLogPrefixMask().
TimePointCache LogManager::logTimePointCache |
Referenced by LogMessageRecord::formatRecordAsText().
|
static |
Created automatically.
Automatically created LogManager object for standard error.
The environment variable USE_STDERR_THREAD
controls whether or not a separate processing thread is enabled. The environment variable STDERR_LINES
can specify the size of the buffer in lines.
|
static |
Created automatically.
Automatically created LogManager object for standard error.
The environment variable USE_STDOUT_THREAD
controls whether or not a separate processing thread is enabled. The environment variable STDOUT_LINES
can specify the size of the buffer in lines.
|
staticprotected |
Referenced by pruneDirectoryPrefix().
|
staticprotected |
Referenced by pruneDirectoryPrefix().
|
protected |
Referenced by pruneDirectoryPrefix(), and setStripLeadingDirectories().
![]() | Generated: Fri Jul 31 2020 18:19:16
Support Information |