C++ bindings for event_loop More...

#include <event_loop_cxx.h>

Collaboration diagram for event_loop_cxx:

Public Types
typedef event_loop__timeout_t	timeout_t

typedef event_loop__fd_ready_cb_t	fd_ready_cb_t

typedef event_loop__timeout_cb_t	timeout_cb_t

typedef event_loop__signal_cb_t	signal_cb_t

Public Member Functions
	event_loop_cxx ()

virtual	~event_loop_cxx ()

virtual void	start ()

virtual void	stop ()

virtual void	add_signal_handler (int signal_number, signal_cb_t cb, void *cb_data)

virtual void	add_signal_handler (int signal_number, event_loop_listener obj, void(event_loop_listener::listener)(int))

virtual void	remove_signal_handler (int signal_number)

virtual timeout_t	add_timeout (double period, timeout_cb_t cb, void *cb_data)

virtual timeout_t	add_timeout (double period, event_loop_listener obj, void(event_loop_listener::listener)(timeout_t))

virtual void	remove_timeout (timeout_t timeout)

virtual void	add_read_fd (int fd, fd_ready_cb_t cb, void *cb_data)

virtual void	add_read_fd (int fd, event_loop_listener obj, void(event_loop_listener::listener)(int))

virtual void	remove_read_fd (int fd)

virtual void	add_write_fd (int fd, fd_ready_cb_t cb, void *cb_data)

virtual void	add_write_fd (int fd, event_loop_listener obj, void(event_loop_listener::listener)(int))

virtual void	remove_write_fd (int fd)

virtual void	add_exception_fd (int fd, fd_ready_cb_t cb, void *cb_data)

virtual void	add_exception_fd (int fd, event_loop_listener obj, void(event_loop_listener::listener)(int))

virtual void	remove_exception_fd (int fd)

virtual event_loop_t	get_obj () const

virtual event_loop_t	take_obj ()

virtual void	set_obj (event_loop_t rhs)

Static Public Member Functions
static event_loop_cxx *	get_instance ()

static void	put_instance ()

Detailed Description

This class provides the C++ bindings for C event_loop objects. The main purpose of this class is to convert the C-style function calls and exception handling in event_loop into C++-style function calls and exception handling.

Member Typedef Documentation

§ timeout_t

typedef event_loop__timeout_t event_loop_cxx::timeout_t

Timeout handle.

§ fd_ready_cb_t

typedef event_loop__fd_ready_cb_t event_loop_cxx::fd_ready_cb_t

File descriptor ready callback.

§ timeout_cb_t

typedef event_loop__timeout_cb_t event_loop_cxx::timeout_cb_t

Timeout expired callback.

§ signal_cb_t

typedef event_loop__signal_cb_t event_loop_cxx::signal_cb_t

Posix asynchronous signal caught callback.

Constructor & Destructor Documentation

§ event_loop_cxx()

event_loop_cxx::event_loop_cxx ( )

inline

Create a new, per-thread event_loop_cxx object that handles file descriptor and timeout events but not Posix asynchronous signal events. The caller is responsible for freeing the object by calling the event_loop_cxx destructor. If memory cannot be allocated, an exception is thrown.

Note: For the main thread, do not create a new event_loop_cxx object using this method; instead, use the singleton returned by get_instance() which has global visibility and can handle Posix asynchronous signals.

References event_loop__new().

Referenced by set_obj().

§ ~event_loop_cxx()

virtual event_loop_cxx::~event_loop_cxx ( )

inlinevirtual

Destructor

References event_loop__delete().

Member Function Documentation

§ get_instance()

static event_loop_cxx* event_loop_cxx::get_instance ( )

inlinestatic

Get the event_loop_cxx wrapper for the single instance of the event_loop class. The single instance is created the first time this method is called. If the instance cannot be created, an exception is thrown.

Note: For the main thread, use the singleton returned by this method which can handle Posix asynchronous signals. Do not use a per-thread instance returned by event_loop_cxx() which cannot handle Posix asynchronous signals.

Returns: single instance wrapper (i.e., main event loop)

References event_loop__get_instance().

Referenced by set_obj().

§ put_instance()

static void event_loop_cxx::put_instance ( )

inlinestatic

Put the single instance of the event_loop class. The single instance is destroyed whenever this method is called which invalidates any outstanding event_loop_cxx wrappers for the single instance. In general, it should only be called before exiting the application if it is called at all.

References event_loop__put_instance().

§ start()

virtual void event_loop_cxx::start ( )

inlinevirtual

This method starts the main event loop which only returns when one of the callbacks registered with the event loop invokes stop().

References event_loop__start().

§ stop()

virtual void event_loop_cxx::stop ( )

inlinevirtual

Call this method from within an event callback or from a different thread in order to stop processing events. This will cause start() to return to its caller. This method is thread-safe. If an error occurs, an exception is thrown.

References event_loop__stop().

§ add_signal_handler() [1/2]

virtual void event_loop_cxx::add_signal_handler	(	int	signal_number,
		signal_cb_t	cb,
		void *	cb_data
	)

inlinevirtual

This method arranges for cb to be called synchronously with cb_data when a Posix asynchronous signal is caught. The big advantage of this is that cb runs in the synchronous context of the event loop's thread instead of in the asynchronous context of a true signal handler. If cb is NULL, the signal is effectively ignored. If the signal cannot be registered, an exception is thrown.

You can change cb and cb_data for a particular signal by calling this method more than once, but only one signal handler can simultaneously be registered per signal.

As a convenience, the event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution. This means you can call any of the methods of this class even from callbacks registered with this class.

If an error occurs, an exception is thrown.

Parameters

[in]	signal_number	signal number
[in]	cb	callback
[in]	cb_data	callback data passed to `cb`

References event_loop__add_signal_handler().

§ add_signal_handler() [2/2]

virtual void event_loop_cxx::add_signal_handler	(	int	signal_number,
		event_loop_listener *	obj,
		void(event_loop_listener::*)(int)	listener
	)

inlinevirtual

This method arranges for the C++ event listener listener to be called synchronously on the object obj when a Posix asynchronous signal is caught. The big advantage of this is that listener runs in the synchronous context of the event loop's thread instead of in the asynchronous context of a true signal handler. If the signal cannot be registered, an exception is thrown.

You can change listener and obj for a particular signal by calling this method more than once, but only one signal handler can simultaneously be registered per signal.

When the Posix asynchronous signal is synchronously detected, the C++ "pointer to member function" listener is invoked on the object obj which must be an instance of a class derived from event_loop_listener. Use the EVENT_LOOP__UPCAST_SIGNAL_HANDLER() macro to properly upcast your "pointer to member function" for your derived class to a type of "pointer to member function" expected by this function. This should look something like the following:

loop->add_signal_handler( signal_number, obj, EVENT_LOOP__UPCAST_SIGNAL_HANDLER(&my_class::my_signal_handler));

As a convenience, the event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution. This means you can call any of the methods of this class even from callbacks registered with this class.

If an error occurs, an exception is thrown.

Parameters

[in]	signal_number	signal number
[in]	obj	object that implements the event listener
[in]	listener	event listener

See also: event_loop_listener; EVENT_LOOP__UPCAST_SIGNAL_HANDLER

§ remove_signal_handler()

virtual void event_loop_cxx::remove_signal_handler ( int signal_number )

inlinevirtual

Remove the the signal handler for the signal signal_number from the list of Posix asynchronous signals handled by the event loop. This causes the default system action for the signal to be restored. If an error occurs, an exception is thrown.

Parameters

[in] signal_number signal number

References event_loop__remove_signal_handler().

§ add_timeout() [1/2]

virtual timeout_t event_loop_cxx::add_timeout	(	double	period,
		timeout_cb_t	cb,
		void *	cb_data
	)

inlinevirtual

This method adds a timeout event that repeatedly schedules itself every period seconds. Because period is a double, timeouts with millisecond resolution can easily be scheduled. The only guarantee regarding when the timeout occurs is that it occurs at least period seconds after it has been scheduled. If period is less than zero, the timeout will not be registered.

The event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution making it possible to remove a timeout from cb itself.

The value returned is the handle for the timeout. It uniquely identifies the timeout and must be passed into remove_timeout() in order to remove the timeout. If you plan on removing the callback from inside cb, you do not need to keep a reference to the value that is returned as it is always passed into your callback.

If an error occurs, an exception is thrown.

Parameters

[in]	period	timeout period
[in]	cb_data	callback data passed to `cb`
[in]	cb	callback

Returns: timeout handle

References event_loop__add_timeout().

§ add_timeout() [2/2]

virtual timeout_t event_loop_cxx::add_timeout	(	double	period,
		event_loop_listener *	obj,
		void(event_loop_listener::*)(timeout_t)	listener
	)

inlinevirtual

This method adds a C++ timeout event listener that repeatedly schedules itself every period seconds. Because period is a double, timeouts with millisecond resolution can easily be scheduled. The only guarantee regarding when the timeout occurs is that it occurs at least period seconds after it has been scheduled. If period is less than zero, the timeout will not be registered.

When the timeout expires, the C++ "pointer to member function" listener is invoked on the object obj which must be an instance of a class derived from event_loop_listener. Use the EVENT_LOOP__UPCAST_TIMEOUT() macro to properly upcast your "pointer to member function" for your derived class to a type of "pointer to member function" expected by this function. This should look something like the following:

loop->add_timeout_listener( period, obj, EVENT_LOOP__UPCAST_TIMEOUT(&my_class::my_timeout));

The event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution making it possible to remove a timeout from listener itself.

The value returned is the handle for the timeout. It uniquely identifies the timeout and must be passed into remove_timeout() in order to remove the timeout. If you plan on removing the listener from inside listener, you do not need to keep a reference to the value that is returned as it is always passed into your listener.

If an error occurs, an exception is thrown.

Parameters

[in]	period	timeout period
[in]	obj	object that implements the event listener
[in]	listener	event listener

Returns: timeout handle

See also: event_loop_listener; EVENT_LOOP__UPCAST_TIMEOUT

§ remove_timeout()

virtual void event_loop_cxx::remove_timeout ( timeout_t timeout )

inlinevirtual

This function removes timeouts registered with add_timeout(). After calling this function, timeout is invalid. If an error occurs, an exception is thrown.

This method can throw an out-of-memory exception. This can happen when this method is called from any timeout callback because this causes this class to be re-entered which requires that the request to remove the timeout be added to a queue so it can be honored later when it is safe to do so.

Parameters

[in] timeout timeout handle

References event_loop__remove_timeout().

§ add_read_fd() [1/2]

virtual void event_loop_cxx::add_read_fd	(	int	fd,
		fd_ready_cb_t	cb,
		void *	cb_data
	)

inlinevirtual

This method adds fd to the list of file descriptors the event loop monitors. The event loop will then call cb with the client-supplied cb_data pointer when fd is ready to be read.

You can change cb and cb_data for a particular file descriptor by calling this method more than once, but only one "read" callback per file descriptor can simultaneously be registered.

As a convenience, the event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution. This means you can call any of the methods of this class even from callbacks registered with this class.

If an error occurs, an exception is thrown.

Parameters

[in]	fd	file descriptor to monitor
[in]	cb	callback
[in]	cb_data	callback data passed to `cb`

References event_loop__add_read_fd().

§ add_read_fd() [2/2]

virtual void event_loop_cxx::add_read_fd	(	int	fd,
		event_loop_listener *	obj,
		void(event_loop_listener::*)(int)	listener
	)

inlinevirtual

This method adds fd to the list of file descriptors the event loop monitors. You can change listener and obj for a particular file descriptor by calling this method more than once, but only one "read" event listener per file descriptor can simultaneously be registered.

When the file descriptor is ready, the C++ "pointer to member function" listener is invoked on the object obj which must be an instance of a class derived from event_loop_listener. Use the EVENT_LOOP__UPCAST_FD_READY() macro to properly upcast your "pointer to member function" for your derived class to a type of "pointer to member function" expected by this function. This should look something like the following:

loop->add_read_fd( fd, obj, EVENT_LOOP__UPCAST_FD_READY(&my_class::my_listener));

As a convenience, the event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution. This means you can call any of the methods of this class even from event listeners registered with this class.

If an error occurs, an exception is thrown.

Parameters

[in]	fd	file descriptor to monitor
[in]	obj	object that implements the event listener
[in]	listener	event listener

See also: event_loop_listener; EVENT_LOOP__UPCAST_FD_READY

§ remove_read_fd()

virtual void event_loop_cxx::remove_read_fd ( int fd )

inlinevirtual

Remove fd from the list of file descriptors the event loop monitors to see when they are ready to be read. If an error occurs, an exception is thrown.

Parameters

[in] fd file descriptor to remove

References event_loop__remove_read_fd().

§ add_write_fd() [1/2]

virtual void event_loop_cxx::add_write_fd	(	int	fd,
		fd_ready_cb_t	cb,
		void *	cb_data
	)

inlinevirtual

This method adds fd to the list of file descriptors the event loop monitors. The event loop will then call cb with the client-supplied cb_data pointer when fd is ready to be written.

You can change cb and cb_data for a particular file descriptor by calling this method more than once, but only one "write" callback per file descriptor can simultaneously be registered.

As a convenience, the event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution. This means you can call any of the methods of this class even from callbacks registered with this class.

If an error occurs, an exception is thrown.

Parameters

[in]	fd	file descriptor to monitor
[in]	cb	callback
[in]	cb_data	callback data passed to `cb`

References event_loop__add_write_fd().

§ add_write_fd() [2/2]

virtual void event_loop_cxx::add_write_fd	(	int	fd,
		event_loop_listener *	obj,
		void(event_loop_listener::*)(int)	listener
	)

inlinevirtual

This method adds fd to the list of file descriptors the event loop monitors. You can change listener and obj for a particular file descriptor by calling this method more than once, but only one "write" event listener per file descriptor can simultaneously be registered.

When the file descriptor is ready, the C++ "pointer to member function" listener is invoked on the object obj which must be an instance of a class derived from event_loop_listener. Use the EVENT_LOOP__UPCAST_FD_READY() macro to properly upcast your "pointer to member function" for your derived class to a type of "pointer to member function" expected by this function. This should look something like the following:

loop->add_write_fd( fd, obj, EVENT_LOOP__UPCAST_FD_READY(&my_class::my_listener));

As a convenience, the event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution. This means you can call any of the methods of this class even from event listeners registered with this class.

If an error occurs, an exception is thrown.

Parameters

[in]	fd	file descriptor to monitor
[in]	obj	object that implements the event listener
[in]	listener	event listener

See also: event_loop_listener; EVENT_LOOP__UPCAST_FD_READY

§ remove_write_fd()

virtual void event_loop_cxx::remove_write_fd ( int fd )

inlinevirtual

Remove fd from the list of file descriptors the event loop monitors to see when they are ready to be written. If an error occurs, an exception is thrown.

Parameters

[in] fd file descriptor to remove

References event_loop__remove_write_fd().

§ add_exception_fd() [1/2]

virtual void event_loop_cxx::add_exception_fd	(	int	fd,
		fd_ready_cb_t	cb,
		void *	cb_data
	)

inlinevirtual

This method adds fd to the list of file descriptors the event loop monitors. The event loop will then call cb with the client-supplied cb_data pointer when fd has an exception.

You can change cb and cb_data for a particular file descriptor by calling this method more than once, but only one "exception" callback per file descriptor can simultaneously be registered.

As a convenience, the event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution. This means you can call any of the methods of this class even from callbacks registered with this class.

If an error occurs, an exception is thrown.

Parameters

[in]	fd	file descriptor to monitor
[in]	cb	callback
[in]	cb_data	callback data passed to `cb`

References event_loop__add_exception_fd().

§ add_exception_fd() [2/2]

virtual void event_loop_cxx::add_exception_fd	(	int	fd,
		event_loop_listener *	obj,
		void(event_loop_listener::*)(int)	listener
	)

inlinevirtual

This method adds fd to the list of file descriptors the event loop monitors. You can change listener and obj for a particular file descriptor by calling this method more than once, but only one "exception" event listener per file descriptor can simultaneously be registered.

When the file descriptor is ready, the C++ "pointer to member function" listener is invoked on the object obj which must be an instance of a class derived from event_loop_listener. Use the EVENT_LOOP__UPCAST_FD_READY() macro to properly upcast your "pointer to member function" for your derived class to a type of "pointer to member function" expected by this function. This should look something like the following:

loop->add_exception_fd( fd, obj, EVENT_LOOP__UPCAST_FD_READY(&my_class::my_listener));

As a convenience, the event_loop_cxx class is re-entrant with respect to the event loop's single thread of execution. This means you can call any of the methods of this class even from event listeners registered with this class.

If an error occurs, an exception is thrown.

Parameters

[in]	fd	file descriptor to monitor
[in]	obj	object that implements the event listener
[in]	listener	event listener

See also: event_loop_listener; EVENT_LOOP__UPCAST_FD_READY

§ remove_exception_fd()

virtual void event_loop_cxx::remove_exception_fd ( int fd )

inlinevirtual

Remove fd from the list of file descriptors the event loop monitors to see when an exception occurs. If an error occurs, an exception is thrown.

Parameters

[in] fd file descriptor to remove

References event_loop__remove_exception_fd().

§ get_obj()

virtual event_loop_t event_loop_cxx::get_obj ( ) const

inlinevirtual

Get the underlying event_loop object.

Returns: underlying object

Referenced by set_obj().

§ take_obj()

virtual event_loop_t event_loop_cxx::take_obj ( )

inlinevirtual

Take the underlying event_loop object. This means the underlying object will not be deleted when the wrapper goes out of scope. Also, because you have taken the underlying object, no other methods should be called on this wrapper's instance. Lastly, after taking the underlying object, it is the caller's responsibility to delete the underlying object by calling event_loop__delete().

Returns: underlying object

§ set_obj()

virtual void event_loop_cxx::set_obj ( event_loop_t rhs )

inlinevirtual

Set the new underlying object to rhs. This causes the old underlying object to be deleted which invalidates any outstanding pointers to or iterators for the old underlying object. Only, per-thread event_loop instances can be set; if rhs is the event_loop singleton, an exception is thrown.

This instance takes ownership of rhs which means rhs will be automatically deleted when the C++ wrapper is deleted. To prevent automatic deletion of rhs, call take_obj() when the C++ wrapper is no longer needed.

Parameters

[in] rhs right-hand side

References event_loop__delete(), event_loop_cxx(), get_instance(), and get_obj().

The documentation for this class was generated from the following file:

event_loop_cxx.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

§ timeout_t

§ fd_ready_cb_t

§ timeout_cb_t

§ signal_cb_t

Constructor & Destructor Documentation

§ event_loop_cxx()

§ ~event_loop_cxx()

Member Function Documentation

§ get_instance()

§ put_instance()

§ start()

§ stop()

§ add_signal_handler() [1/2]

§ add_signal_handler() [2/2]

§ remove_signal_handler()

§ add_timeout() [1/2]

§ add_timeout() [2/2]

§ remove_timeout()

§ add_read_fd() [1/2]

§ add_read_fd() [2/2]

§ remove_read_fd()

§ add_write_fd() [1/2]

§ add_write_fd() [2/2]

§ remove_write_fd()

§ add_exception_fd() [1/2]

§ add_exception_fd() [2/2]

§ remove_exception_fd()

§ get_obj()

§ take_obj()

§ set_obj()