UClient linux implementation with support for synchronous extra functions. More...

#include <usyncclient.hh>

Inheritance diagram for urbi::USyncClient:

Collaboration diagram for urbi::USyncClient:

Classes
struct	options
	Option structure for USyncClient construction. More...
struct	send_options
	Options for send(), rather than multiplying the overloads. More...
Public Types
typedef boost::function1< void, USyncClient * >	connect_callback_type
typedef UClient	super_type
typedef super_type::error_type	error_type
	Error code.
Public Member Functions
	USyncClient (const std::string &host, unsigned port=URBI_PORT, size_t buflen=URBI_BUFLEN, const USyncClient::options &opt=options())
	Create a new connection to an Urbi Server.
	~USyncClient ()
UMessage *	syncGet (const char *expression,...)
	Synchronously evaluate an Urbi expression.
UMessage *	syncGet (const std::string &exp)
	Synchronously evaluate an Urbi expression.
UMessage *	syncGet (libport::utime_t useconds, const char *expression,...)
	Likewise, with a timeout.
UMessage *	syncGetTag (const char expression, const char mtag, const char *mmod,...)
	Synchronously evaluate an Urbi expression, specifying the tag and modifiers to prepend to it.
UMessage *	syncGetTag (libport::utime_t useconds, const char expression, const char mtag, const char *mmod,...)
	Likewise, with timeout.
int	syncSend (const void *buffer, size_t length)
	Send given buffer without copying it.
int	syncGetImage (const char cameraDevice, void buffer, size_t &buffersize, int format, int transmitFormat, size_t &width, size_t &height, libport::utime_t useconds=0)
	Get an image in a synchronous way.
int	syncGetValue (const char *valName, UValue &val, libport::utime_t useconds=0)
	Get the value of any device in a synchronous way.
int	syncGetValue (const char tag, const char valName, UValue &val, libport::utime_t useconds=0)
int	syncGetDevice (const char *device, ufloat &val, libport::utime_t useconds=0)
	Get the value of device.val in a synchronous way.
int	syncGetResult (const char *command, ufloat &val, libport::utime_t useconds=0)
	Execute an URBI command, return the resulting double value.
int	syncGetNormalizedDevice (const char *device, ufloat &val, libport::utime_t useconds=0)
	Get the normalized value of a device in a synchronous way.
int	syncGetDevice (const char device, const char field, ufloat &val, libport::utime_t useconds=0)
	Get a field of a device in a synchronous way.
int	syncGetSound (const char *device, int duration, USound &sound, libport::utime_t useconds=0)
	Get sound for duration milliseconds in buffer.
UMessage *	waitForTag (const std::string &tag, libport::utime_t useconds=0)
	Wait until a message with specified tag is received.
void	lockQueue ()
	Must be called once before sending message associated with waitForTag.
virtual void	notifyCallbacks (const UMessage &msg)
	Overriding UAbstractclient implementation.
bool	processEvents (libport::utime_t timeout=-1)
	Check message queue for pending messages, notify callbacks synchronously.
void	stopCallbackThread ()
	Stop the callback processing thread.
void	callbackThread ()
void	setSynchronous (bool enable)
	Enable synchronous transmission of messages to the callbacks.
void	waitForKernelVersion (bool hasProcessingThread)
void	setDefaultOptions (const USyncClient::send_options &opt)
const USyncClient::send_options &	getOptions (const USyncClient::send_options &opt=USyncClient::send_options::default_options) const
virtual void	onConnect ()
bool	isCallbackThread () const
Static Public Member Functions
static boost::shared_ptr < libport::Finally >	listen (const std::string &host, const std::string &port, boost::system::error_code &erc, connect_callback_type connectCallback, size_t buflen=URBI_BUFLEN, bool startCallbackThread=true)
	Listen on the specified host:port pair.
Protected Member Functions
virtual error_type	onClose ()
	Executed when closing connection.
UMessage *	syncGet_ (const char *expression, va_list &arg, const send_options &options=send_options::default_options)
	Synchronously ask the server for the value of an expression.
int	joinCallbackThread_ ()
Static Protected Member Functions
static libport::Socket *	onAccept (connect_callback_type l, size_t buflen, bool startThread)
Protected Attributes
libport::Semaphore	sem_
libport::Semaphore	callbackSem_
std::list< UMessage * >	queue
libport::Lockable	queueLock_
UMessage *	message_
	When locked waiting for a specific tag, notifyCallbacks will store the received message here, and waitForTag will get it there.
libport::Semaphore	syncLock_
std::string	syncTag
send_options	default_options_
bool	stopCallbackThread_
pthread_t	cbThread
libport::Semaphore	stopCallbackSem_
connect_callback_type	connectCallback_
bool	waitingFromPollThread_
bool	synchronous_

Detailed Description

UClient linux implementation with support for synchronous extra functions.

This class provides extra functions to synchronously request values. These functions can safely be called frow within a callback function.

All callbacks will be called in a separate thread created in the constructor. When one of those callbacks calls a synchronous function, new incoming messages are kept on hold until the response from the synchronous call is received.

If you want to call these callbacks in a different thread, call stopCallbackThread(), then regularly call processEvents(). Each call will call callbacks for all pending messages in the current thread.

Definition at line 54 of file usyncclient.hh.

Member Typedef Documentation

typedef boost::function1<void, USyncClient*> urbi::USyncClient::connect_callback_type

Definition at line 57 of file usyncclient.hh.

typedef super_type::error_type urbi::USyncClient::error_type

Error code.

0 iff no error. Other values are unspecified.

Reimplemented from urbi::UAbstractClient.

Definition at line 59 of file usyncclient.hh.

typedef UClient urbi::USyncClient::super_type

Definition at line 58 of file usyncclient.hh.

Constructor & Destructor Documentation

urbi::USyncClient::USyncClient	(	const std::string &	host,
		unsigned	port = `URBI_PORT`,
		size_t	buflen = `URBI_BUFLEN`,
		const USyncClient::options &	opt = `options()`
	)

Create a new connection to an Urbi Server.

Blocks until the connection is established.

Parameters:

host	The host to connect to.
port	the port number to connect to, defaults to URBI_PORT.
buflen	Size of reception buffer, defaults to URBI_BUFLEN.
opt	Parameters of this USyncClient.

Definition at line 64 of file usyncclient.cc.

References callbackSem_, callbackThread(), cbThread, connectCallback_, urbi::defaultClient, urbi::UAbstractClient::error(), and urbi::UClient::start().

Referenced by onAccept().

urbi::USyncClient::~USyncClient ( )

Definition at line 109 of file usyncclient.cc.

References cbThread, and joinCallbackThread_().

Member Function Documentation

void urbi::USyncClient::callbackThread ( )

Definition at line 122 of file usyncclient.cc.

References callbackSem_, notifyCallbacks(), queue, queueLock_, sem_, stopCallbackSem_, and stopCallbackThread_.

Referenced by USyncClient().

const USyncClient::send_options & urbi::USyncClient::getOptions ( const USyncClient::send_options & opt = USyncClient::send_options::default_options ) const

Definition at line 584 of file usyncclient.cc.

References urbi::USyncClient::send_options::default_options, and default_options_.

Referenced by syncGet_().

bool urbi::USyncClient::isCallbackThread ( ) const

Returns:: true if the current thread is the callback thread.

Definition at line 625 of file usyncclient.cc.

References cbThread.

Referenced by urbi::impl::RemoteUContextImpl::markDataSent().

int urbi::USyncClient::joinCallbackThread_ ( ) [protected]

Definition at line 189 of file usyncclient.cc.

References cbThread, and stopCallbackThread().

Referenced by ~USyncClient().

boost::shared_ptr< libport::Finally > urbi::USyncClient::listen	(	const std::string &	host,
		const std::string &	port,
		boost::system::error_code &	erc,
		connect_callback_type	connectCallback,
		size_t	buflen = `URBI_BUFLEN`,
		bool	startCallbackThread = `true`
	)		`[static]`

Listen on the specified host:port pair.

Bind an USyncClient on each connection, and call connectCallback. Socket ownership is transfered to the callback.

Returns:: a handle on the listening socket. Destroy it to stop listening.

Definition at line 607 of file usyncclient.cc.

References urbi::destroySocket(), and onAccept().

void urbi::USyncClient::lockQueue ( )

Must be called once before sending message associated with waitForTag.

Definition at line 637 of file usyncclient.cc.

References queueLock_.

Referenced by urbi::impl::RemoteUContextImpl::setSerializationMode(), and urbi::impl::RemoteUContextImpl::syncGet().

void urbi::USyncClient::notifyCallbacks ( const UMessage & msg ) [virtual]

Overriding UAbstractclient implementation.

Reimplemented from urbi::UAbstractClient.

Definition at line 201 of file usyncclient.cc.

References message_, queue, queueLock_, sem_, synchronous_, syncLock_, syncTag, urbi::UMessage::tag, and waitingFromPollThread_.

Referenced by callbackThread(), urbi::impl::RemoteUContextImpl::onTimer(), urbi::impl::RemoteUObjectImpl::onUpdate(), and processEvents().

libport::Socket * urbi::USyncClient::onAccept	(	connect_callback_type	l,
		size_t	buflen,
		bool	startThread
	)		`[static, protected]`

Definition at line 596 of file usyncclient.cc.

References USyncClient().

Referenced by listen().

USyncClient::error_type urbi::USyncClient::onClose ( ) [protected, virtual]

Executed when closing connection.

Reimplemented from urbi::UClient.

Definition at line 293 of file usyncclient.cc.

References callbackSem_, urbi::UAbstractClient::closed_, sem_, and stopCallbackThread_.

void urbi::USyncClient::onConnect ( ) [virtual]

Reimplemented from urbi::UClient.

Definition at line 569 of file usyncclient.cc.

References connectCallback_.

bool urbi::USyncClient::processEvents ( libport::utime_t timeout = -1 )

Check message queue for pending messages, notify callbacks synchronously.

Parameters:

timeout If different -1 process events for at most timeout microseconds. This is useful if you don't want processEvents() to take to much time if there are many many pending messages.

Returns:: true if at least one message was processed, false otherwise. Callbacks functions are called synchronously in the caller thread.

Definition at line 166 of file usyncclient.cc.

References notifyCallbacks(), queue, queueLock_, and sem_.

Referenced by waitForKernelVersion().

void urbi::USyncClient::setDefaultOptions ( const USyncClient::send_options & opt )

Definition at line 578 of file usyncclient.cc.

References default_options_.

void urbi::USyncClient::setSynchronous ( bool enable )

Enable synchronous transmission of messages to the callbacks.

When enabled, the message processing thread is bypassed, and callbacks are called synchronously by the network thread. The result is a lower latency, but some configurations of synchronous calls will not work anymore.

Definition at line 631 of file usyncclient.cc.

References synchronous_.

void urbi::USyncClient::stopCallbackThread ( )

Stop the callback processing thread.

The user is responsible for calling processEvents() regularily once this function has been called.

Definition at line 153 of file usyncclient.cc.

References sem_, stopCallbackSem_, stopCallbackThread_, and syncLock_.

Referenced by joinCallbackThread_().

UMessage * urbi::USyncClient::syncGet	(	const char *	expression,
			...
	)

Synchronously evaluate an Urbi expression.

The expression must not start with a tag or channel.

Definition at line 334 of file usyncclient.cc.

References syncGet_().

Referenced by urbi::impl::RemoteUContextImpl::RemoteUContextImpl(), syncGet(), syncGetDevice(), syncGetImage(), syncGetNormalizedDevice(), syncGetResult(), and syncGetSound().

UMessage * urbi::USyncClient::syncGet ( const std::string & exp )

Synchronously evaluate an Urbi expression.

The expression must not start with a tag or channel.

Definition at line 344 of file usyncclient.cc.

References syncGet().

UMessage * urbi::USyncClient::syncGet	(	libport::utime_t	useconds,
		const char *	expression,
			...
	)

Likewise, with a timeout.

Definition at line 353 of file usyncclient.cc.

References syncGet_().

UMessage * urbi::USyncClient::syncGet_	(	const char *	expression,
		va_list &	arg,
		const send_options &	options = `send_options::default_options`
	)		`[protected]`

Synchronously ask the server for the value of an expression.

Parameters:

expression	the Urbi expression to evaluate. It must be a single expression and must not start with a tag. It's a printf-like format string.
arg	the arguments for the expression
options	what tag to use and so forth.

Returns:: the resulting message, or 0 in case of error.

Definition at line 307 of file usyncclient.cc.

References urbi::UAbstractClient::effective_send(), urbi::compatibility::evaluate_in_channel_close(), urbi::compatibility::evaluate_in_channel_open(), getOptions(), urbi::UAbstractClient::kernelMajor(), urbi::USyncClient::send_options::mtag_, urbi::UAbstractClient::pack(), queueLock_, urbi::UAbstractClient::rc, urbi::UAbstractClient::sendBuffer, urbi::LockableOstream::sendBufferLock, urbi::USyncClient::send_options::timeout_, urbi::UAbstractClient::vpack(), and waitForTag().

Referenced by syncGet(), and syncGetTag().

int urbi::USyncClient::syncGetDevice	(	const char *	device,
		ufloat &	val,
		libport::utime_t	useconds = `0`
	)

Get the value of device.val in a synchronous way.

Returns:: 1 on success, 0 on failure.

Definition at line 483 of file usyncclient.cc.

References urbi::getValue(), and syncGet().

int urbi::USyncClient::syncGetDevice	(	const char *	device,
		const char *	field,
		ufloat &	val,
		libport::utime_t	useconds = `0`
	)

Get a field of a device in a synchronous way.

Returns:: 1 on success, 0 on failure.

Definition at line 498 of file usyncclient.cc.

References urbi::getValue(), and syncGet().

int urbi::USyncClient::syncGetImage	(	const char *	cameraDevice,
		void *	buffer,
		size_t &	buffersize,
		int	format,
		int	transmitFormat,
		size_t &	width,
		size_t &	height,
		libport::utime_t	useconds = `0`
	)