IOStrands provide guaranteed serialized event handling. More...

#include <IOStrand.hpp>

Inheritance diagram for Sirikata::Network::IOStrand:

Collaboration diagram for Sirikata::Network::IOStrand:

Classes
class	WrappedHandler
Public Types
typedef std::tr1::unordered_map< const char *, uint32 >	TagCountMap
Public Member Functions
	~IOStrand ()
	Destroy the strand.
const String &	name () const
	Get the name of this IOStrand.
IOService &	service () const
	Get an IOService associated with this strand.
void	dispatch (const IOCallback &handler, const char *tag=NULL)
	Request that the given handler be invoked, possibly before returning, on this strand.
void	post (const IOCallback &handler, const char *tag=NULL)
	Request that the given handler be appended to the event queue and invoked on this strand at a later time.
void	post (const Duration &waitFor, const IOCallback &handler, const char *tag=NULL)
	Request that the given handler be appended to the event queue and invoked on this strand at a later time.
IOCallback	wrap (const IOCallback &handler)
	Wrap the given handler so that it will be handled in this strand.
template<typename CallbackType >
WrappedHandler< CallbackType >	wrap (const CallbackType &handler)
	Wrap the given handler so that it will be handled in this strand.
Private Member Functions
	IOStrand (IOService &io, const String &name)
	Construct an IOStrand associated with the given IOService.
Private Attributes
IOService &	mService
InternalIOStrand *	mImpl
const String	mName
Friends
class	IOService
class	StrandTCPSocket

Detailed Description

IOStrands provide guaranteed serialized event handling.

Strands allow you to wrap events so that they may be dispatched to any currently running IOService (in thread), but guarantees that no two event handlers in the same strand will be executed concurrently. This is a a useful synchronization primitive, allow user code to avoid having to use locks explicitly and allowing the IOService to make the best use of available threads instead of locking operations to specific threads, causing unnecessary thread switching overhead.

Note that strands are never directly allocated -- instead, they are acquired from an existing IOService.

Member Typedef Documentation

typedef std::tr1::unordered_map<const char*, uint32> Sirikata::Network::IOStrand::TagCountMap

Constructor & Destructor Documentation

Sirikata::Network::IOStrand::IOStrand	(	IOService &	io,
		const String &	name
	)		`[private]`

Construct an IOStrand associated with the given IOService.

References mImpl.

Sirikata::Network::IOStrand::~IOStrand ( )

Destroy the strand.

Outstanding events on the strand will be handled safely, i.e. non-concurrently.

References mImpl, and mService.

Member Function Documentation

void Sirikata::Network::IOStrand::dispatch	(	const IOCallback &	handler,
		const char *	tag = `NULL`
	)

Request that the given handler be invoked, possibly before returning, on this strand.

Parameters:

handler	the handler callback to be called
tag	a string descriptor of the handler for debugging

References mImpl, mService, and Sirikata::Timer::now().

const String& Sirikata::Network::IOStrand::name ( ) const [inline]

Get the name of this IOStrand.

Not necessarily unique, but ideally it will be.

void Sirikata::Network::IOStrand::post	(	const IOCallback &	handler,
		const char *	tag = `NULL`
	)

Request that the given handler be appended to the event queue and invoked on this strand at a later time.

The handler is guaranteed not to be invoked will not be invoked during this method call.

Parameters:

handler	the handler callback to be called
tag	a string descriptor of the handler for debugging

References mImpl, mService, and Sirikata::Timer::now().

void Sirikata::Network::IOStrand::post	(	const Duration &	waitFor,
		const IOCallback &	handler,
		const char *	tag = `NULL`
	)

Request that the given handler be appended to the event queue and invoked on this strand at a later time.

Regardless of the wait duration requested, the handler is guaranteed not to be invoked during this method call.

Parameters:

waitFor	the length of time to wait before invoking the handler
handler	the handler callback to be called
tag	a string descriptor of the handler for debugging

References mImpl, mService, Sirikata::Timer::now(), and Sirikata::Network::IOService::post().

IOService & Sirikata::Network::IOStrand::service ( ) const

Get an IOService associated with this strand.

References mService.

Referenced by Sirikata::Network::ASIOSocketWrapper::createSocket().

template<typename CallbackType >

IOStrand::WrappedHandler< CallbackType > Sirikata::Network::IOStrand::wrap ( const CallbackType & handler )

Wrap the given handler so that it will be handled in this strand.

Parameters:

handler the handler which should be wrapped