forward declaration for TokenHub More...

#include <TokenHub.hh>

Inheritance diagram for utility::signals::TokenHub< ResultType, Signal >:

Public Types
typedef Super::Size	Size

Public Types inherited from utility::signals::BufferedSignalHub< ReturnType, Signal >
typedef Super::Size	Size

typedef std::vector< Signal >	Buffer

Public Types inherited from utility::signals::SignalHub< ReturnType, Signal >
typedef platform::Size	Size

Public Member Functions
	TokenHub ()
	default constructor More...

virtual	~TokenHub ()
	default destructor More...

Size	receive_tokens_from (TokenHub const &src)
	receive tokenized connections from source and remove them from source More...

Size	n_tokens () const
	number of tokenized connections More...

void	clear_tokens ()
	clear only tokenized connections, will invalidate all tokens More...

template<typename MemFn , typename Ptr >
Link	connect_tokenize (MemFn fn, Ptr ptr)
	connect and tokenize an observer's member function More...

template<typename MemFn , typename Ptr >
bool	disconnect (MemFn fn, Ptr ptr)
	disconnect an observer's member function More...

template<typename MemFn , typename Ptr >
bool	disconnect_tokenize (MemFn fn, Ptr ptr)
	disconnect an observer's tokenized member function More...

Public Member Functions inherited from utility::signals::BufferedSignalHub< ReturnType, Signal >
	BufferedSignalHub ()
	default constructor More...

virtual	~BufferedSignalHub ()=default
	default destructor More...

void	buffer ()
	block signals and buffer them for release upon unblocking More...

virtual void	unblock ()
	allow signals to be sent and release any signals that were buffered More...

bool	buffering () const
	are signals being buffered? More...

void	clear_buffer ()
	clear the buffer More...

Size	buffer_size () const
	number of signals left in the buffer More...

Public Member Functions inherited from utility::signals::SignalHub< ReturnType, Signal >
	SignalHub ()
	default constructor More...

virtual	~SignalHub ()
	default destructor More...

void	operator() (Signal s)
	send signal to all observers connected to the hub More...

Size	size () const
	number of connections to the hub More...

void	block ()
	block signals from being sent More...

bool	blocked () const
	are signals blocked? More...

void	clear ()
	clear all connections More...

Link	connect (MemFn fn, Ptr ptr)
	connect an observer's member function to this hub More...

bool	disconnect (MemFn fn, Ptr ptr)
	disconnect an observer's member function from this hub More...

Size	receive_linkunits_from (SignalHub const &src)
	transfer linkunits from source to this SignalHub More...

Links	current_links () const
	return a copy of the list of links currently being managed by this SignalHub More...

Protected Member Functions
virtual void	send_signal (Signal s)
	send signal to both regular and tokenized connections More...

Protected Member Functions inherited from utility::signals::BufferedSignalHub< ReturnType, Signal >
void	release_buffer ()
	release the signals in the buffer More...

virtual bool	signal_allowed (Signal const s)
	is signal allowed to be passed? More...

Protected Member Functions inherited from utility::signals::SignalHub< ReturnType, Signal >
Link	connect (MemFn fn, Ptr ptr, LinkUnits &links) const
	connect an observer's member function to the given LinkUnits More...

bool	disconnect (MemFn fn, Ptr ptr, LinkUnits &links) const
	disconnect an observer's member function from the given LinkUnits More...

virtual void	after_send ()
	initiate an action after send (no-op in SignalHub) More...

LinkUnits::iterator	find_connection (Functor f, LinkUnits &links) const
	find a specific connection to this hub More...

void	send (Signal s, LinkUnits &links) const
	send signal to all links taking into account validity and local blocking More...

void	invalidate_all (LinkUnits &links) const
	invalidate and destroy internals of all links More...

void	remove_invalid (LinkUnits &links) const
	remove and destroy internals of invalid links More...

void	deallocate (LinkUnit &lu) const
	deallocate function stored in a LinkUnit More...

LinkUnits &	linkunits ()
	returns the list of LinkUnits More...

Private Types
typedef BufferedSignalHub < ReturnType, Signal >	Super

typedef Super::LinkUnits	LinkUnits

Private Member Functions
	TokenHub (TokenHub const &rval)
	disallow copy constructor More...

TokenHub &	operator= (TokenHub const &rval)
	disallow copy assignment More...

Private Attributes
LinkUnits	tokens_
	tokenized observer function objects More...

Additional Inherited Members
Protected Types inherited from utility::signals::SignalHub< ReturnType, Signal >
typedef boost::function1 < ReturnType, Signal >	Function

typedef std::vector< LinkUnitOP >	LinkUnits

typedef std::vector< Link >	Links

Detailed Description

template<typename ResultType, typename Signal>
class utility::signals::TokenHub< ResultType, Signal >

forward declaration for TokenHub

BufferedSignalHub capable of passing observers.

If an observer's member function is connected with the 'tokenize' flag, then this function is allowed to permanently pass from a source TokenHub to a destination TokenHub via a call to receive_tokens_from(), which will erase the observer function from the source hub. The observer member function, in effect, becomes a single token which is intended to be passed from Subject to Subject upon copy (see remarks in receive_tokens_from() for different behavior in copy construct vs copy assign). Invalidating the Link will stop the token from being passed from Subject to Subject. Use the token ability with care, as it depends on the programmer to consistently do the right thing and make sure Observer and Subject(s) do not loose sync with each other. Observers that communicate via a tokenized member function are recommended to follow the following guidelines:

the Observer should be created and never destroyed as long as any Subject objects are in use
the Observer should not store a pointer to its Subject

Warning: Only use this class when necessary, as usage of the token ability can introduce too much ambiguity into deciding whether an Observer or Subject still exists. Most users should think about using a BufferedSignalHub instead and managing the connections manually.

Member Typedef Documentation

template<typename ResultType , typename Signal >

typedef Super::LinkUnits utility::signals::TokenHub< ResultType, Signal >::LinkUnits

private

template<typename ResultType , typename Signal >

typedef Super::Size utility::signals::TokenHub< ResultType, Signal >::Size

template<typename ResultType , typename Signal >

typedef BufferedSignalHub< ReturnType, Signal > utility::signals::TokenHub< ResultType, Signal >::Super

private

Constructor & Destructor Documentation

template<typename ResultType , typename Signal >

utility::signals::TokenHub< ResultType, Signal >::TokenHub ( )

inline

default constructor

template<typename ResultType , typename Signal >

virtual utility::signals::TokenHub< ResultType, Signal >::~TokenHub ( )

inlinevirtual

default destructor

References utility::signals::SignalHub< ReturnType, Signal >::invalidate_all(), and utility::signals::TokenHub< ResultType, Signal >::tokens_.

template<typename ResultType , typename Signal >

utility::signals::TokenHub< ResultType, Signal >::TokenHub ( TokenHub< ResultType, Signal > const & rval )

private

disallow copy constructor

Member Function Documentation

template<typename ResultType , typename Signal >

void utility::signals::TokenHub< ResultType, Signal >::clear_tokens ( )

inline

clear only tokenized connections, will invalidate all tokens

References utility::signals::SignalHub< ReturnType, Signal >::invalidate_all(), and utility::signals::TokenHub< ResultType, Signal >::tokens_.

template<typename ResultType , typename Signal >

template<typename MemFn , typename Ptr >

Link utility::signals::TokenHub< ResultType, Signal >::connect_tokenize	(	MemFn	fn,
		Ptr	ptr
	)

inline

connect and tokenize an observer's member function

Template Parameters

MemFn unary member function

Parameters

fn	pointer to observer's member function
ptr	pointer to observer object

Returns: Link that can manage the connection

References utility::signals::SignalHub< ReturnType, Signal >::connect(), and utility::signals::TokenHub< ResultType, Signal >::tokens_.

template<typename ResultType , typename Signal >

template<typename MemFn , typename Ptr >

bool utility::signals::TokenHub< ResultType, Signal >::disconnect	(	MemFn	fn,
		Ptr	ptr
	)

inline

disconnect an observer's member function

will search both regular and tokenized functions

Template Parameters

MemFn unary member function

Parameters

fn	pointer to observer's member function
ptr	pointer to observer object

Returns: true if disconnect successful, false if connection does not exist

References utility::signals::SignalHub< ReturnType, Signal >::disconnect(), and utility::signals::TokenHub< ResultType, Signal >::tokens_.

Referenced by utility::signals::TokenHub< ResultType, Signal >::disconnect_tokenize().

template<typename ResultType , typename Signal >

template<typename MemFn , typename Ptr >

bool utility::signals::TokenHub< ResultType, Signal >::disconnect_tokenize	(	MemFn	fn,
		Ptr	ptr
	)

inline

disconnect an observer's tokenized member function

Parameters

fn	pointer to observer's member function
ptr	pointer to observer object

Returns: true if disconnect successful, false if connection does not exist

References utility::signals::TokenHub< ResultType, Signal >::disconnect(), and utility::signals::TokenHub< ResultType, Signal >::tokens_.

template<typename ResultType , typename Signal >

Size utility::signals::TokenHub< ResultType, Signal >::n_tokens ( ) const

inline

number of tokenized connections

References utility::signals::SignalHub< ReturnType, Signal >::remove_invalid(), and utility::signals::TokenHub< ResultType, Signal >::tokens_.

template<typename ResultType , typename Signal >

TokenHub& utility::signals::TokenHub< ResultType, Signal >::operator= ( TokenHub< ResultType, Signal > const & rval )

private

disallow copy assignment

template<typename ResultType , typename Signal >

Size utility::signals::TokenHub< ResultType, Signal >::receive_tokens_from ( TokenHub< ResultType, Signal > const & src )

inline

receive tokenized connections from source and remove them from source

Remarks: Use this within either copy constructor or copy assignment of Subject. Use within a copy constructor will give behavior that tends to keep the token from descending too far down in the call graph, while use within copy assignment will give behavior that can drill deep down into the call graph and has the potential of getting trapped at the lowest level.