CRotatingAsyncFileLog Class Reference
[Asynchronous I/O, Interfaces, FileIO, Log files and the pluggable logging system]

Inheritance diagram for CRotatingAsyncFileLog:

[legend]

Collaboration diagram for CRotatingAsyncFileLog:

[legend]

List of all members.

---

Detailed Description

A class that implements JetByteTools::ILogMessages to provide an asynchronous file log that uses overlapped I/O to perform writes to the log file. The log can be set to automatically rotate (i.e. create a new log file) after a set period of time or when the file grows to a particular size.

Public Types
enum	RotationPeriod { NoRotation, Hourly, Daily, Weekly }
enum	FirstFileTimestamp { DoNotIncludeTimestampOnFirstFile, IncludeTimestampOnFirstFile }
enum	EmptyLogFileHandling { PreserveEmptyLogFiles, DeleteEmptyLogFiles }
typedef unsigned long	DataLength
Public Member Functions
	CRotatingAsyncFileLog (const JetByteTools::Win32::_tstring &filenameBase, const RotationPeriod rotationPeriod=Daily, const FirstFileTimestamp firstFileTimestamp=IncludeTimestampOnFirstFile, const EmptyLogFileHandling emptyLogFileHandling=PreserveEmptyLogFiles, const long maxPendingWrites=CAsyncFileWriter::NoLimitToPendingWrites)
	Construct an async file log using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase.YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that firstFileTimestamp can be used to suppress the timestamp, -HHMMSS section, of the first file name generated. Note that emptyLogFileHandling can be used to prevent the creation of empty log files if no logging occurs during a log files activity period. Note that maxPendingWrites can be used to limit the number of pending write operations to prevent uncontrolled 'non paged pool' memory usage if log messages are produced at a rate faster than they can be written to the disk. Note that once the limit is reached all writes become synchronous until the number of pending writes has dropped below the limit again. Timers will be managed with a default timer queue. File I/O will be done using a default I/O thread pool with a single thread and buffers will be allocated from a default allocator with a buffer size of 100 bytes and a pool size of 10.
	CRotatingAsyncFileLog (const JetByteTools::Win32::_tstring &filenameBase, JetByteTools::Win32::IQueueTimers &timerQueue, JetByteTools::IO::IIOPool &pool, JetByteTools::IO::IAllocateBuffers &allocator, const RotationPeriod rotationPeriod=Daily, const FirstFileTimestamp firstFileTimestamp=IncludeTimestampOnFirstFile, const EmptyLogFileHandling emptyLogFileHandling=PreserveEmptyLogFiles, const long maxPendingWrites=CAsyncFileWriter::NoLimitToPendingWrites)
	Construct an async file log using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase.YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that firstFileTimestamp can be used to suppress the timestamp, -HHMMSS section, of the first file name generated. Note that emptyLogFileHandling can be used to prevent the creation of empty log files if no logging occurs during a log files activity period. Note that maxPendingWrites can be used to limit the number of pending write operations to prevent uncontrolled 'non paged pool' memory usage if log messages are produced at a rate faster than they can be written to the disk. Note that once the limit is reached all writes become synchronous until the number of pending writes has dropped below the limit again. File I/O will be done using the threads in the IIOPool provided and data buffers obtained from the supplied buffer allocator.
	CRotatingAsyncFileLog (const JetByteTools::Win32::_tstring &filenameBase, JetByteTools::Win32::IQueueTimers &timerQueue, JetByteTools::IO::IIOPool &pool, JetByteTools::IO::IAllocateBuffers &allocator, const JetByteTools::Win32::IProvideLocalTime &timeProvider, const RotationPeriod rotationPeriod=Daily, const FirstFileTimestamp firstFileTimestamp=IncludeTimestampOnFirstFile, const EmptyLogFileHandling emptyLogFileHandling=PreserveEmptyLogFiles, const long maxPendingWrites=CAsyncFileWriter::NoLimitToPendingWrites)
	Construct an async file log using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase.YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that firstFileTimestamp can be used to suppress the timestamp, -HHMMSS section, of the first file name generated. Note that emptyLogFileHandling can be used to prevent the creation of empty log files if no logging occurs during a log files activity period. Note that maxPendingWrites can be used to limit the number of pending write operations to prevent uncontrolled 'non paged pool' memory usage if log messages are produced at a rate faster than they can be written to the disk. Note that once the limit is reached all writes become synchronous until the number of pending writes has dropped below the limit again. File I/O will be done using the threads in the IIOPool provided and data buffers obtained from the supplied buffer allocator.
	~CRotatingAsyncFileLog ()
	Waits for any pending writes to complete and then destroys the log object.
bool	PerformWritesOnThisThread () const
	Returns true if writes are issued directly from the calling thread and false if they are marshalled to the thread pool.
JetByteTools::Win32::_tstring	GetCurrentLogFileName () const
	Returns the complete file name of the current log, i.e the filename that was set plus the date/time portion that is generated automatically.
virtual void	SetThreadIdentifier (const std::string &identifier)
	Sets the identifier used in the log for the current thread to the supplied string. The thread identifier defaults to the thread id in the form "XXX: ", the string supplied as an identifier does not need to include the ": " as this will be appended automatically. It can be any string that will help you to identify the thread concerned.
virtual void	SetThreadIdentifier (const std::wstring &identifier)
	Sets the identifier used in the log for the current thread to the supplied string. The thread identifier defaults to the thread id in the form "XXX: ", the string supplied as an identifier does not need to include the ": " as this will be appended automatically. It can be any string that will help you to identify the thread concerned.
virtual void	SetLogName (const std::string &filenameBase)
	Sets the name of the log file using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase-YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that if the file log was created with includeTimeInFirstFilename set to false then the file name will NOT include the -HHMMSS section. Note that this creates a new log file with the specified name, it does NOT rename the existing log file. All subsequent automatic log file creation will use the newly supplied filenameBase rather than any that was supplied in the constructor.
virtual void	SetLogName (const std::wstring &filenameBase)
	Sets the name of the log file using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase-YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that if the file log was created with includeTimeInFirstFilename set to false then the file name will NOT include the -HHMMSS section. Note that this creates a new log file with the specified name, it does NOT rename the existing log file. All subsequent automatic log file creation will use the newly supplied filenameBase rather than any that was supplied in the constructor.
virtual void	LogMessage (const std::string &message)
	Logs the message to the log.
virtual void	LogMessage (const std::wstring &message)
	Logs the message to the log.
virtual void	LogMessage (const char *const pString)
	Logs the message to the log.
virtual void	LogMessage (const wchar_t *const pString)
	Logs the message to the log.
virtual void	LogMessage (const char *const pString, const DataLength stringLength)
	Logs the message to the log.
virtual void	LogMessage (const wchar_t *const pString, const DataLength stringLength)
	Logs the message to the log.
virtual HANDLE	GetWaitHandle () const
	Access a HANDLE to wait on by passing it to one of the Wait Functions.
virtual void	Wait () const
	Wait indefinitely for the object to become signalled.
virtual bool	Wait (const Milliseconds timeoutMillis) const
	Wait, with a time limit, for the object to become signalled.
Static Public Member Functions
static void	Wait (HANDLE handle)
	Wait indefinitely for the supplied handle to become signalled.
static bool	Wait (HANDLE handle, const Milliseconds timeout)
	Wait, with a time limit, for the supplied handle to become signalled.
static bool	WaitWithMessageLoop (HANDLE handle, const Milliseconds timeout)
static bool	WaitWithMessageLoop (HANDLE handle, const Milliseconds timeout, const DWORD removeFlags)
static bool	WaitWithMessageLoop (const DWORD numHandles, HANDLE *pHandles, const Milliseconds timeout)
static bool	WaitWithMessageLoop (const DWORD numHandles, HANDLE *pHandles, DWORD &signalledHandle, const Milliseconds timeout)
static bool	WaitWithMessageLoop (const DWORD numHandles, HANDLE *pHandles, DWORD &signalledHandle, const Milliseconds timeout, const DWORD removeFlags)

---

Member Typedef Documentation

typedef unsigned long DataLength [inherited]

---

Member Enumeration Documentation

enum RotationPeriod

Enumerator:

NoRotation
Hourly
Daily
Weekly

enum FirstFileTimestamp

Enumerator:

DoNotIncludeTimestampOnFirstFile
IncludeTimestampOnFirstFile	The first file does not include a -HHMMSS portion in the file name. The first file generated includes a timetsamp portion, -HHMMSS in the generated file name.

enum EmptyLogFileHandling

Enumerator:

PreserveEmptyLogFiles
DeleteEmptyLogFiles	Empty log files are created if no logging occurs during a file's active period. Delete empty log files when they are closed

---

Constructor & Destructor Documentation

CRotatingAsyncFileLog	(	const JetByteTools::Win32::_tstring &	filenameBase,
		const RotationPeriod	rotationPeriod = Daily,
		const FirstFileTimestamp	firstFileTimestamp = IncludeTimestampOnFirstFile,
		const EmptyLogFileHandling	emptyLogFileHandling = PreserveEmptyLogFiles,
		const long	maxPendingWrites = CAsyncFileWriter::NoLimitToPendingWrites
	)			[explicit]

Construct an async file log using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase.YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that firstFileTimestamp can be used to suppress the timestamp, -HHMMSS section, of the first file name generated. Note that emptyLogFileHandling can be used to prevent the creation of empty log files if no logging occurs during a log files activity period. Note that maxPendingWrites can be used to limit the number of pending write operations to prevent uncontrolled 'non paged pool' memory usage if log messages are produced at a rate faster than they can be written to the disk. Note that once the limit is reached all writes become synchronous until the number of pending writes has dropped below the limit again. Timers will be managed with a default timer queue. File I/O will be done using a default I/O thread pool with a single thread and buffers will be allocated from a default allocator with a buffer size of 100 bytes and a pool size of 10.

CRotatingAsyncFileLog	(	const JetByteTools::Win32::_tstring &	filenameBase,
		JetByteTools::Win32::IQueueTimers &	timerQueue,
		JetByteTools::IO::IIOPool &	pool,
		JetByteTools::IO::IAllocateBuffers &	allocator,
		const RotationPeriod	rotationPeriod = Daily,
		const FirstFileTimestamp	firstFileTimestamp = IncludeTimestampOnFirstFile,
		const EmptyLogFileHandling	emptyLogFileHandling = PreserveEmptyLogFiles,
		const long	maxPendingWrites = CAsyncFileWriter::NoLimitToPendingWrites
	)

Construct an async file log using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase.YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that firstFileTimestamp can be used to suppress the timestamp, -HHMMSS section, of the first file name generated. Note that emptyLogFileHandling can be used to prevent the creation of empty log files if no logging occurs during a log files activity period. Note that maxPendingWrites can be used to limit the number of pending write operations to prevent uncontrolled 'non paged pool' memory usage if log messages are produced at a rate faster than they can be written to the disk. Note that once the limit is reached all writes become synchronous until the number of pending writes has dropped below the limit again. File I/O will be done using the threads in the IIOPool provided and data buffers obtained from the supplied buffer allocator.

CRotatingAsyncFileLog	(	const JetByteTools::Win32::_tstring &	filenameBase,
		JetByteTools::Win32::IQueueTimers &	timerQueue,
		JetByteTools::IO::IIOPool &	pool,
		JetByteTools::IO::IAllocateBuffers &	allocator,
		const JetByteTools::Win32::IProvideLocalTime &	timeProvider,
		const RotationPeriod	rotationPeriod = Daily,
		const FirstFileTimestamp	firstFileTimestamp = IncludeTimestampOnFirstFile,
		const EmptyLogFileHandling	emptyLogFileHandling = PreserveEmptyLogFiles,
		const long	maxPendingWrites = CAsyncFileWriter::NoLimitToPendingWrites
	)

Construct an async file log using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase.YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that firstFileTimestamp can be used to suppress the timestamp, -HHMMSS section, of the first file name generated. Note that emptyLogFileHandling can be used to prevent the creation of empty log files if no logging occurs during a log files activity period. Note that maxPendingWrites can be used to limit the number of pending write operations to prevent uncontrolled 'non paged pool' memory usage if log messages are produced at a rate faster than they can be written to the disk. Note that once the limit is reached all writes become synchronous until the number of pending writes has dropped below the limit again. File I/O will be done using the threads in the IIOPool provided and data buffers obtained from the supplied buffer allocator.

~CRotatingAsyncFileLog

(

)

Waits for any pending writes to complete and then destroys the log object.

---

Member Function Documentation

bool PerformWritesOnThisThread

(

)

const

Returns true if writes are issued directly from the calling thread and false if they are marshalled to the thread pool.

_tstring GetCurrentLogFileName

(

)

const

Returns the complete file name of the current log, i.e the filename that was set plus the date/time portion that is generated automatically.

void SetThreadIdentifier

(

const std::string &

identifier

)

[virtual]

Sets the identifier used in the log for the current thread to the supplied string. The thread identifier defaults to the thread id in the form "XXX: ", the string supplied as an identifier does not need to include the ": " as this will be appended automatically. It can be any string that will help you to identify the thread concerned.

Implements ILogMessages.

void SetThreadIdentifier

(

const std::wstring &

identifier

)

[virtual]

Sets the identifier used in the log for the current thread to the supplied string. The thread identifier defaults to the thread id in the form "XXX: ", the string supplied as an identifier does not need to include the ": " as this will be appended automatically. It can be any string that will help you to identify the thread concerned.

Implements ILogMessages.

void SetLogName

(

const std::string &

filenameBase

)

[virtual]

Sets the name of the log file using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase-YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that if the file log was created with includeTimeInFirstFilename set to false then the file name will NOT include the -HHMMSS section. Note that this creates a new log file with the specified name, it does NOT rename the existing log file. All subsequent automatic log file creation will use the newly supplied filenameBase rather than any that was supplied in the constructor.

Implements ILogMessages.

void SetLogName

(

const std::wstring &

filenameBase

)

[virtual]

Sets the name of the log file using the supplied filenameBase for the base of the log file name; the actual file name is formed as follows: filenameBase-YYYYMMDD-HHMMSS.log. If filenameBase ends with ".log" then this is automatically stripped to leave the actual file name in the form shown above. Note that if the file log was created with includeTimeInFirstFilename set to false then the file name will NOT include the -HHMMSS section. Note that this creates a new log file with the specified name, it does NOT rename the existing log file. All subsequent automatic log file creation will use the newly supplied filenameBase rather than any that was supplied in the constructor.

Implements ILogMessages.

void LogMessage

(

const std::string &

message

)

[virtual]

Logs the message to the log.

Implements ILogMessages.

void LogMessage

(

const std::wstring &

message

)

[virtual]

Logs the message to the log.

Implements ILogMessages.

void LogMessage

(

const char *const

pString

)

[virtual]

Logs the message to the log.

Implements ILogMessages.

void LogMessage

(

const wchar_t *const

pString

)

[virtual]

Logs the message to the log.

Implements ILogMessages.

void LogMessage	(	const char *const	pString,
		const DataLength	stringLength
	)			[virtual]

Logs the message to the log.

Implements ILogMessages.

void LogMessage	(	const wchar_t *const	pString,
		const DataLength	stringLength
	)			[virtual]

Logs the message to the log.

Implements ILogMessages.

HANDLE GetWaitHandle

(

)

const [virtual]

Access a HANDLE to wait on by passing it to one of the Wait Functions.

Implements IWaitable.

void Wait

(

)

const [virtual]

Wait indefinitely for the object to become signalled.

Implements IWaitable.

bool Wait

(

const Milliseconds

timeout

)

const [virtual]

Wait, with a time limit, for the object to become signalled.

Implements IWaitable.

void Wait

(

HANDLE

handle

)

[static, inherited]

Wait indefinitely for the supplied handle to become signalled.

bool Wait	(	HANDLE	handle,
		const Milliseconds	timeout
	)			[static, inherited]

Wait, with a time limit, for the supplied handle to become signalled.

bool WaitWithMessageLoop	(	HANDLE	handle,
		const Milliseconds	timeout
	)			[static, inherited]

bool WaitWithMessageLoop	(	HANDLE	handle,
		const Milliseconds	timeout,
		const DWORD	removeFlags
	)			[static, inherited]

bool WaitWithMessageLoop	(	const DWORD	numHandles,
		HANDLE *	pHandles,
		const Milliseconds	timeout
	)			[static, inherited]

bool WaitWithMessageLoop	(	const DWORD	numHandles,
		HANDLE *	pHandles,
		DWORD &	signalledHandle,
		const Milliseconds	timeout
	)			[static, inherited]

bool WaitWithMessageLoop	(	const DWORD	numHandles,
		HANDLE *	pHandles,
		DWORD &	signalledHandle,
		const Milliseconds	timeout,
		const DWORD	removeFlags
	)			[static, inherited]

---