CAsyncFileWriterEx Class Reference
[Asynchronous I/O, I/O Buffers, FileIO]

Inheritance diagram for CAsyncFileWriterEx:

[legend]

Collaboration diagram for CAsyncFileWriterEx:

[legend]

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
typedef unsigned long	DataLength
enum	Flags {   MarshalWritesToThreadPool = 0x01, ExecuteWritesOnCallingThread = 0x02, ExecuteWritesOnCallingThreadIfSafe = 0x03, MarshallingFlagsMask = 0x0F,   NoBuffering = 0x10, WriteThrough = 0x20, PreExtendFile = 0x40, BufferingFlagsMask = 0xF0 }
Public Member Functions
	CAsyncFileWriterEx (const JetByteTools::Win32::_tstring &filename, Callback &callback, IIOPool &pool, IAllocateBuffers &allocator, const long maxPendingWrites=CAsyncFileWriter::NoLimitToPendingWrites)
	Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the IAllocateBuffers instance and push any errors that occur to the CAsyncFileWriter::Callback interface.
	~CAsyncFileWriterEx ()
void	Write (const BYTE *const pData, const DataLength dataLength)
	Write the data to the file.
void	Write (const Data *const pData, const DataLength count)
	Write the data to the file.
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 (IBuffer *pBuffer)
	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.
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 timeout) 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)
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.
static const long	NoLimitToPendingWrites = 0
	Used to specify to the constructors that you do not wish to limit the maximum number of writes that can be pending. If you DO decide to impose a limit then the limit causes Writes to become synchronous once the limit is reached.
Protected Member Functions
void	GetNextWriteOffset (LARGE_INTEGER &offset, const DataLength dataLength)
void	RequestWrite (IBuffer &buffer)
Classes
struct	Data
	A simple structure to enable 'gather' style multiple buffer writes with minimal data copying. More...

---

Member Typedef Documentation

typedef unsigned long DataLength

Reimplemented from CAsyncFileWriter.

---

Member Enumeration Documentation

enum Flags [inherited]

Enumerator:

MarshalWritesToThreadPool
ExecuteWritesOnCallingThread
ExecuteWritesOnCallingThreadIfSafe
MarshallingFlagsMask
NoBuffering
WriteThrough
PreExtendFile
BufferingFlagsMask

---

Constructor & Destructor Documentation

CAsyncFileWriterEx	(	const JetByteTools::Win32::_tstring &	filename,
		Callback &	callback,
		IIOPool &	pool,
		IAllocateBuffers &	allocator,
		const long	maxPendingWrites = CAsyncFileWriter::NoLimitToPendingWrites
	)

Write to the specified file asynchronously using overlapped I/O via the threads in the supplied IIOPool using buffers provided by the IAllocateBuffers instance and push any errors that occur to the CAsyncFileWriter::Callback interface.

~CAsyncFileWriterEx

(

)

---

Member Function Documentation

void Write	(	const BYTE *const	pData,
		const DataLength	dataLength
	)

Write the data to the file.

void Write	(	const Data *const	pData,
		const DataLength	count
	)

Write the data to the file.

bool PerformWritesOnThisThread

(

)

const [inherited]

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

void Write

(

IBuffer *

pBuffer

)

[inherited]

Write the contents of the IBuffer to the file.

void Close

(

)

[inherited]

Close the file.

void NotifyOnNoWrites

(

const bool

notifyNowIfNoWritesPending = true

)

[inherited]

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 [inherited]

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 [inherited]

Returns the current size of the file in bytes.

HANDLE GetWaitHandle

(

)

const [virtual, inherited]

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

Implements IWaitable.

void Wait

(

)

const [virtual, inherited]

Wait indefinitely for the object to become signalled.

Implements IWaitable.

virtual bool Wait

(

const Milliseconds

timeout

)

const [virtual, inherited]

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.

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

void RequestWrite

(

IBuffer &

buffer

)

[protected, inherited]

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]

---

Member Data Documentation

const LARGE_INTEGER DoNotPreExtendFile [static, inherited]

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.

const long NoLimitToPendingWrites = 0 [static, inherited]

Used to specify to the constructors that you do not wish to limit the maximum number of writes that can be pending. If you DO decide to impose a limit then the limit causes Writes to become synchronous once the limit is reached.

---