The C++ framework for developing highly scalable, high performance servers on Windows platforms.

CAsyncFileWriter Class Reference
[Asynchronous I/OI/O BuffersFileIO]

Inheritance diagram for CAsyncFileWriter:
Collaboration diagram for CAsyncFileWriter:

List of all members.


Detailed Description

A class that implements IHandler to provide an asynchronous file writer that uses overlapped I/O to perform writes to the file. Any errors that occur during the asynchronous file writes are reported via the CAsyncFileWriter::Callback interface.

Public Types

enum  Flags {
  MarshalWritesToThreadPool = 0x01, ExecuteWritesOnCallingThread = 0x02, MarshallingFlagsMask = 0x0F, NoBuffering = 0x10,
  WriteThrough = 0x20, PreExtendFile = 0x40, BufferingFlagsMask = 0xF0
}
typedef unsigned long DataLength

Public Member Functions

 CAsyncFileWriter (const JetByteTools::Win32::_tstring &filename, Callback &callback, IIOPool &pool, ILimitPendingWrites &writeLimiter=CPendingWriteLimiter::NoLimitLimiter, const long flags=MarshalWritesToThreadPool, const LARGE_INTEGER &fileSize=DoNotPreExtendFile)
 Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.
 CAsyncFileWriter (const JetByteTools::Win32::_tstring &filename, Callback &callback, IIOPool &pool, IMonitorAsyncFileWriter &monitor, ILimitPendingWrites &writeLimiter=CPendingWriteLimiter::NoLimitLimiter, const long flags=MarshalWritesToThreadPool, const LARGE_INTEGER &fileSize=DoNotPreExtendFile)
 Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Monitor write progress using the supplied monitor. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.
 CAsyncFileWriter (const JetByteTools::Win32::_tstring &filename, JetByteTools::Win32::CSmartHandle &handle, Callback &callback, IIOPool &pool, ILimitPendingWrites &writeLimiter=CPendingWriteLimiter::NoLimitLimiter, const long flags=MarshalWritesToThreadPool, const LARGE_INTEGER &fileSize=DoNotPreExtendFile)
 Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Note: that the file MUST have been opened in overlapped mode! Note: takes ownership of the file, the handle will be closed when the object is destroyed. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.
 CAsyncFileWriter (const JetByteTools::Win32::_tstring &filename, JetByteTools::Win32::CSmartHandle &handle, Callback &callback, IIOPool &pool, IMonitorAsyncFileWriter &monitor, ILimitPendingWrites &writeLimiter=CPendingWriteLimiter::NoLimitLimiter, const long flags=MarshalWritesToThreadPool, const LARGE_INTEGER &fileSize=DoNotPreExtendFile)
 Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Monitor write progress using the supplied monitor. Note: that the file MUST have been opened in overlapped mode! Note: takes ownership of the file, the handle will be closed when the object is destroyed. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.
 CAsyncFileWriter (JetByteTools::Win32::CSmartHandle &handle, Callback &callback, IIOPool &pool, ILimitPendingWrites &writeLimiter=CPendingWriteLimiter::NoLimitLimiter, const long flags=MarshalWritesToThreadPool, const LARGE_INTEGER &fileSize=DoNotPreExtendFile)
 Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Note: that the file MUST have been opened in overlapped mode! Note: takes ownership of the file, the handle will be closed when the object is destroyed. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.
 CAsyncFileWriter (JetByteTools::Win32::CSmartHandle &handle, Callback &callback, IIOPool &pool, IMonitorAsyncFileWriter &monitor, ILimitPendingWrites &writeLimiter=CPendingWriteLimiter::NoLimitLimiter, const long flags=MarshalWritesToThreadPool, const LARGE_INTEGER &fileSize=DoNotPreExtendFile)
 Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Monitor write progress using the supplied monitor. Note: that the file MUST have been opened in overlapped mode! Note: takes ownership of the file, the handle will be closed when the object is destroyed. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.
virtual ~CAsyncFileWriter ()
bool PerformWritesOnThisThread () const
 Returns true if writes are issued directly from the calling thread and false if they are marshalled to the thread pool.
void Write (CSmartBuffer &buffer)
 Write the contents of the IBuffer to the file.
void Close ()
 Close the file.
void NotifyOnNoWrites (const bool notifyNowIfNoWritesPending=true)
 Causes the file writer to call Callback::OnLastWrite() when the count of pending writes reaches zero. If you call this and pass true for notifyNowIfNoWritesPending and there currently no outstanding writes then the callback is called immediately. Note: You may get multiple calls to OnLastWrite() for a single 'last write' completion as we don't bother to guard against the race condition between this call and the actual write completions. It's best to call this when you would otherwise call Wait(), i.e. after the last write that you intend to issue on this file writer.
const
JetByteTools::Win32::_tstring
GetFilenameIfKnown () const
 Returns the name of the file if the file writer was created from a file name and an empty string if the file writer was created from a file handle.
__int64 GetFileSize () const
 Returns the current size of the file in bytes.
HANDLE GetWaitHandle () const override
 Access a HANDLE to wait on by passing it to one of the Wait Functions.
void Wait () const override
 Wait indefinitely for the object to become signalled.
bool Wait (const Milliseconds timeout) const override
 Wait, with a time limit, for the object to become signalled. If you want to wait for 0 milliseconds and you get an "ambiguous call" with the Handle version then use IsSignalled() which is the same as Wait(0).
virtual bool IsSignalled () const
 Returns true if the object is signalled and false if it isn't; doesn't block.

Static Public Member Functions

static
JetByteTools::Win32::CSmartHandle 
OpenSuitableFile (const JetByteTools::Win32::_tstring &filename, const long flags=0)
static
JetByteTools::Win32::CSmartHandle 
CreateSuitableFile (const JetByteTools::Win32::_tstring &filename, const long flags=0)
static
JetByteTools::Win32::CSmartHandle 
TryCreateSuitableFile (const JetByteTools::Win32::_tstring &filename, const long flags=0)
static void WaitForHandle (HANDLE handle)
 Wait indefinitely for the supplied handle to become signalled.
static bool WaitForHandle (HANDLE handle, const Milliseconds timeout)
 Wait, with a time limit, for the supplied handle to become signalled.
static bool WaitWithMessageLoop (const HANDLE handle, const Milliseconds timeout)
static bool WaitWithMessageLoop (const HANDLE handle, const Milliseconds timeout, const DWORD removeFlags)
static bool WaitWithMessageLoop (const DWORD numHandles, const HANDLE *pHandles, const Milliseconds timeout)
static bool WaitWithMessageLoop (const DWORD numHandles, const HANDLE *pHandles, DWORD &signalledHandle, const Milliseconds timeout)
static bool WaitWithMessageLoop (const DWORD numHandles, const HANDLE *pHandles, DWORD &signalledHandle, const Milliseconds timeout, const DWORD removeFlags)

Static Public Attributes

static const
LARGE_INTEGER 
DoNotPreExtendFile
 Used to specify to the constructors that you do not wish to extend the size of the file during construction and then trim it to the correct size when all data has been written. Note that file systems extend files synchronously (See Richter 2008). By specifying a file size during construction we can extend the size of the file and allow the actual data writes to occur asynchronously.

Protected Member Functions

void GetNextWriteOffset (LARGE_INTEGER &offset, const DataLength dataLength)
void RequestWrite (CSmartBuffer &buffer)

Classes

class  Callback
 An interface for users of the CAsyncFileWriter to be notified of any errors that occur during the asynchronous write operations on the file. More...

Member Typedef Documentation

typedef unsigned long DataLength

Reimplemented in CAsyncFileWriterEx.


Member Enumeration Documentation

enum Flags

Enumerator:
MarshalWritesToThreadPool 
ExecuteWritesOnCallingThread 
MarshallingFlagsMask 
NoBuffering 
WriteThrough 
PreExtendFile 
BufferingFlagsMask 


Constructor & Destructor Documentation

CAsyncFileWriter ( const JetByteTools::Win32::_tstring filename,
Callback callback,
IIOPool pool,
ILimitPendingWrites writeLimiter = CPendingWriteLimiter::NoLimitLimiter,
const long  flags = MarshalWritesToThreadPool,
const LARGE_INTEGER &  fileSize = DoNotPreExtendFile 
)

Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.

CAsyncFileWriter ( const JetByteTools::Win32::_tstring filename,
Callback callback,
IIOPool pool,
IMonitorAsyncFileWriter monitor,
ILimitPendingWrites writeLimiter = CPendingWriteLimiter::NoLimitLimiter,
const long  flags = MarshalWritesToThreadPool,
const LARGE_INTEGER &  fileSize = DoNotPreExtendFile 
)

Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Monitor write progress using the supplied monitor. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.

CAsyncFileWriter ( const JetByteTools::Win32::_tstring filename,
JetByteTools::Win32::CSmartHandle handle,
Callback callback,
IIOPool pool,
ILimitPendingWrites writeLimiter = CPendingWriteLimiter::NoLimitLimiter,
const long  flags = MarshalWritesToThreadPool,
const LARGE_INTEGER &  fileSize = DoNotPreExtendFile 
)

Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Note: that the file MUST have been opened in overlapped mode! Note: takes ownership of the file, the handle will be closed when the object is destroyed. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.

CAsyncFileWriter ( const JetByteTools::Win32::_tstring filename,
JetByteTools::Win32::CSmartHandle handle,
Callback callback,
IIOPool pool,
IMonitorAsyncFileWriter monitor,
ILimitPendingWrites writeLimiter = CPendingWriteLimiter::NoLimitLimiter,
const long  flags = MarshalWritesToThreadPool,
const LARGE_INTEGER &  fileSize = DoNotPreExtendFile 
)

Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Monitor write progress using the supplied monitor. Note: that the file MUST have been opened in overlapped mode! Note: takes ownership of the file, the handle will be closed when the object is destroyed. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.

CAsyncFileWriter ( JetByteTools::Win32::CSmartHandle handle,
Callback callback,
IIOPool pool,
ILimitPendingWrites writeLimiter = CPendingWriteLimiter::NoLimitLimiter,
const long  flags = MarshalWritesToThreadPool,
const LARGE_INTEGER &  fileSize = DoNotPreExtendFile 
)

Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Note: that the file MUST have been opened in overlapped mode! Note: takes ownership of the file, the handle will be closed when the object is destroyed. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.

CAsyncFileWriter ( JetByteTools::Win32::CSmartHandle handle,
Callback callback,
IIOPool pool,
IMonitorAsyncFileWriter monitor,
ILimitPendingWrites writeLimiter = CPendingWriteLimiter::NoLimitLimiter,
const long  flags = MarshalWritesToThreadPool,
const LARGE_INTEGER &  fileSize = DoNotPreExtendFile 
)

Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the caller and push any errors that occur to the CAsyncFileWriter::Callback interface. Monitor write progress using the supplied monitor. Note: that the file MUST have been opened in overlapped mode! Note: takes ownership of the file, the handle will be closed when the object is destroyed. Limits the maximum number of pending writes to the supplied limit 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. Sets the file size to the supplied value in the constructor and then trims the file to the actual size of the written bytes when the file is closed; this allows us to work around the fact that file systems extend files synchronously.

~CAsyncFileWriter (  )  [virtual]


Member Function Documentation

static JetByteTools::Win32::CSmartHandle OpenSuitableFile ( const JetByteTools::Win32::_tstring filename,
const long  flags = 0 
) [static]

static JetByteTools::Win32::CSmartHandle CreateSuitableFile ( const JetByteTools::Win32::_tstring filename,
const long  flags = 0 
) [static]

static JetByteTools::Win32::CSmartHandle TryCreateSuitableFile ( const JetByteTools::Win32::_tstring filename,
const long  flags = 0 
) [static]

bool PerformWritesOnThisThread (  )  const

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

void Write ( CSmartBuffer buffer  ) 

Write the contents of the IBuffer to the file.

void Close (  ) 

Close the file.

void NotifyOnNoWrites ( const bool  notifyNowIfNoWritesPending = true  ) 

Causes the file writer to call Callback::OnLastWrite() when the count of pending writes reaches zero. If you call this and pass true for notifyNowIfNoWritesPending and there currently no outstanding writes then the callback is called immediately. Note: You may get multiple calls to OnLastWrite() for a single 'last write' completion as we don't bother to guard against the race condition between this call and the actual write completions. It's best to call this when you would otherwise call Wait(), i.e. after the last write that you intend to issue on this file writer.

const _tstring & GetFilenameIfKnown (  )  const

Returns the name of the file if the file writer was created from a file name and an empty string if the file writer was created from a file handle.

__int64 GetFileSize (  )  const

Returns the current size of the file in bytes.

HANDLE GetWaitHandle (  )  const [override, virtual]

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

Implements IWaitable.

void Wait (  )  const [override, virtual]

Wait indefinitely for the object to become signalled.

Implements IWaitable.

bool Wait ( const Milliseconds  timeout  )  const [override, virtual]

Wait, with a time limit, for the object to become signalled. If you want to wait for 0 milliseconds and you get an "ambiguous call" with the Handle version then use IsSignalled() which is the same as Wait(0).

Implements IWaitable.

void GetNextWriteOffset ( LARGE_INTEGER &  offset,
const DataLength  dataLength 
) [protected]

void RequestWrite ( CSmartBuffer buffer  )  [protected]

bool IsSignalled (  )  const [virtual, inherited]

Returns true if the object is signalled and false if it isn't; doesn't block.

void WaitForHandle ( HANDLE  handle  )  [static, inherited]

Wait indefinitely for the supplied handle to become signalled.

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

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

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

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

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

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

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


Member Data Documentation

const LARGE_INTEGER DoNotPreExtendFile [static]

Used to specify to the constructors that you do not wish to extend the size of the file during construction and then trim it to the correct size when all data has been written. Note that file systems extend files synchronously (See Richter 2008). By specifying a file size during construction we can extend the size of the file and allow the actual data writes to occur asynchronously.


Generated on Wed Jan 17 15:20:46 2018 for The Server Framework - v6.9.1 by doxygen 1.5.3