Event loop implementation. More...

#include <proxy-io.h>

Collaboration diagram for mp::EventLoop:

Public Member Functions
	EventLoop (const char exe_name, LogFn log_fn, void context=nullptr)
	Construct event loop object with default logging options. More...

	EventLoop (const char exe_name, LogOptions log_opts, void context=nullptr)
	Construct event loop object with specified logging options. More...

	EventLoop (const char exe_name, std::function< void(bool, std::string)> old_callback, void context=nullptr)
	Backwards-compatible constructor for previous (deprecated) logging callback signature. More...

	~EventLoop ()

void	loop ()
	Run event loop. More...

void	post (kj::Function< void()> fn)
	Run function on event loop thread. More...

template<typename Callable >
void	sync (Callable &&callable)
	Wrapper around EventLoop::post that takes advantage of the fact that callable will not go out of scope to avoid requirement that it be copyable. More...

void	addAsyncCleanup (std::function< void()> fn)
	Register cleanup function to run on asynchronous worker thread without blocking the event loop thread. More...

void	startAsyncThread () MP_REQUIRES(m_mutex)
	Start asynchronous worker thread if necessary. More...

bool	done () const MP_REQUIRES(m_mutex)
	Check if loop should exit. More...

kj::Function< void()> *m_post_fn	MP_GUARDED_BY (m_mutex)
	Callback function to run on event loop thread during post() or sync() call. More...

std::optional< CleanupList > m_async_fns	MP_GUARDED_BY (m_mutex)
	Callback functions to run on async thread. More...

int m_num_clients	MP_GUARDED_BY (m_mutex)=0
	Number of clients holding references to ProxyServerBase objects that reference this event loop. More...

Public Attributes
const char *	m_exe_name
	Process name included in thread names so combined debug output from multiple processes is easier to understand. More...

std::thread::id	m_thread_id = std::this_thread::get_id()
	ID of the event loop thread. More...

std::thread	m_async_thread
	Handle of an async worker thread. More...

int	m_wait_fd = -1
	Pipe read handle used to wake up the event loop thread. More...

int	m_post_fd = -1
	Pipe write handle used to wake up the event loop thread. More...

Mutex	m_mutex
	Mutex and condition variable used to post tasks to event loop and async thread. More...

std::condition_variable	m_cv

kj::AsyncIoContext	m_io_context
	Capnp IO context. More...

LoggingErrorHandler	m_error_handler {*this}
	Capnp error handler. Needs to outlive m_task_set. More...

std::unique_ptr< kj::TaskSet >	m_task_set
	Capnp list of pending promises. More...

std::list< Connection >	m_incoming_connections
	List of connections. More...

LogOptions	m_log_opts
	Logging options. More...

void *	m_context
	External context pointer. More...

Detailed Description

Event loop implementation.

Cap'n Proto threading model is very simple: all I/O operations are asynchronous and must be performed on a single thread. This includes:

Code starting an asynchronous operation (calling a function that returns a promise object)
Code notifying that an asynchronous operation is complete (code using a fulfiller object)
Code handling a completed operation (code chaining or waiting for a promise)

All of this code needs to access shared state, and there is no mutex that can be acquired to lock this state because Cap'n Proto assumes it will only be accessed from one thread. So all this code needs to actually run on one thread, and the EventLoop::loop() method is the entry point for this thread. ProxyClient and ProxyServer objects that use other threads and need to perform I/O operations post to this thread using EventLoop::post() and EventLoop::sync() methods.

Specifically, because ProxyClient methods can be called from arbitrary threads, and ProxyServer methods can run on arbitrary threads, ProxyClient methods use the EventLoop thread to send requests, and ProxyServer methods use the thread to return results.

Based on https://groups.google.com/d/msg/capnproto/TuQFF1eH2-M/g81sHaTAAQAJ

Definition at line 238 of file proxy-io.h.

Constructor & Destructor Documentation

◆ EventLoop() [1/3]

mp::EventLoop::EventLoop	(	const char *	exe_name,
		LogFn	log_fn,
		void *	context = `nullptr`
	)

inline

Construct event loop object with default logging options.

Definition at line 242 of file proxy-io.h.

◆ EventLoop() [2/3]

mp::EventLoop::EventLoop	(	const char *	exe_name,
		LogOptions	log_opts,
		void *	context = `nullptr`
	)

Construct event loop object with specified logging options.

Definition at line 199 of file proxy.cpp.

◆ EventLoop() [3/3]

mp::EventLoop::EventLoop	(	const char *	exe_name,
		std::function< void(bool, std::string)>	old_callback,
		void *	context = `nullptr`
	)

inline

Backwards-compatible constructor for previous (deprecated) logging callback signature.

Definition at line 249 of file proxy-io.h.

◆ ~EventLoop()

mp::EventLoop::~EventLoop ( )

Definition at line 212 of file proxy.cpp.

Member Function Documentation

◆ addAsyncCleanup()

void mp::EventLoop::addAsyncCleanup ( std::function< void()> fn )

Register cleanup function to run on asynchronous worker thread without blocking the event loop thread.

Definition at line 176 of file proxy.cpp.

Here is the call graph for this function:

◆ done()

bool mp::EventLoop::done ( ) const

Check if loop should exit.

Definition at line 315 of file proxy.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ loop()

void mp::EventLoop::loop ( )

Run event loop.

Does not return until shutdown. This should only be called once from the m_thread_id thread. This will block until the m_num_clients reference count is 0.

Definition at line 227 of file proxy.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ MP_GUARDED_BY() [1/3]

kj::Function< void()> *m_post_fn mp::EventLoop::MP_GUARDED_BY ( m_mutex )

Callback function to run on event loop thread during post() or sync() call.

◆ MP_GUARDED_BY() [2/3]

std::optional< CleanupList > m_async_fns mp::EventLoop::MP_GUARDED_BY ( m_mutex )

Callback functions to run on async thread.

◆ MP_GUARDED_BY() [3/3]

int m_num_clients mp::EventLoop::MP_GUARDED_BY ( m_mutex )

pure virtual

Number of clients holding references to ProxyServerBase objects that reference this event loop.

◆ post()

void mp::EventLoop::post ( kj::Function< void()> fn )

Run function on event loop thread.

Does not return until function completes. Must be called while the loop() function is active.

Definition at line 271 of file proxy.cpp.

Here is the call graph for this function:

◆ startAsyncThread()

void mp::EventLoop::startAsyncThread ( )

Start asynchronous worker thread if necessary.

This is only done if there are ProxyServerBase::m_impl objects that need to be destroyed asynchronously, without tying up the event loop thread. This can happen when an interface does not declare a destroy() method that would allow the client to wait for the destructor to finish and run it on a dedicated thread. It can also happen whenever this is a broken connection and the client is no longer around to call the destructors and the server objects need to be garbage collected. In both cases, it is important that ProxyServer::m_impl destructors do not run on the eventloop thread because they may need it to do I/O if they perform other IPC calls.

Definition at line 289 of file proxy.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sync()

template<typename Callable >

void mp::EventLoop::sync ( Callable && callable )

inline

Wrapper around EventLoop::post that takes advantage of the fact that callable will not go out of scope to avoid requirement that it be copyable.

Definition at line 269 of file proxy-io.h.

Here is the caller graph for this function:

Member Data Documentation

◆ m_async_thread

std::thread mp::EventLoop::m_async_thread

Handle of an async worker thread.

Joined on destruction. Unset if async method has not been called.

Definition at line 303 of file proxy-io.h.

◆ m_context

void* mp::EventLoop::m_context

External context pointer.

Definition at line 342 of file proxy-io.h.

◆ m_cv

std::condition_variable mp::EventLoop::m_cv

Definition at line 324 of file proxy-io.h.

◆ m_error_handler

LoggingErrorHandler mp::EventLoop::m_error_handler {*this}

Capnp error handler. Needs to outlive m_task_set.

Definition at line 330 of file proxy-io.h.

◆ m_exe_name

const char* mp::EventLoop::m_exe_name

Process name included in thread names so combined debug output from multiple processes is easier to understand.

Definition at line 296 of file proxy-io.h.

◆ m_incoming_connections

std::list<Connection> mp::EventLoop::m_incoming_connections

List of connections.

Definition at line 336 of file proxy-io.h.

◆ m_io_context

kj::AsyncIoContext mp::EventLoop::m_io_context

Capnp IO context.

Definition at line 327 of file proxy-io.h.

◆ m_log_opts

LogOptions mp::EventLoop::m_log_opts

Logging options.

Definition at line 339 of file proxy-io.h.

◆ m_mutex

Mutex mp::EventLoop::m_mutex

Mutex and condition variable used to post tasks to event loop and async thread.

Definition at line 323 of file proxy-io.h.

◆ m_post_fd

int mp::EventLoop::m_post_fd = -1

Pipe write handle used to wake up the event loop thread.

Definition at line 315 of file proxy-io.h.

◆ m_task_set

std::unique_ptr<kj::TaskSet> mp::EventLoop::m_task_set

Capnp list of pending promises.

Definition at line 333 of file proxy-io.h.

◆ m_thread_id

std::thread::id mp::EventLoop::m_thread_id = std::this_thread::get_id()

ID of the event loop thread.

Definition at line 299 of file proxy-io.h.

◆ m_wait_fd

int mp::EventLoop::m_wait_fd = -1

Pipe read handle used to wake up the event loop thread.

Definition at line 312 of file proxy-io.h.

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

src/ipc/libmultiprocess/include/mp/proxy-io.h
src/ipc/libmultiprocess/src/mp/proxy.cpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ EventLoop() [1/3]

◆ EventLoop() [2/3]

◆ EventLoop() [3/3]

◆ ~EventLoop()

Member Function Documentation

◆ addAsyncCleanup()

◆ done()

◆ loop()

◆ MP_GUARDED_BY() [1/3]

◆ MP_GUARDED_BY() [2/3]

◆ MP_GUARDED_BY() [3/3]

◆ post()

◆ startAsyncThread()

◆ sync()

Member Data Documentation

◆ m_async_thread

◆ m_context

◆ m_cv

◆ m_error_handler

◆ m_exe_name

◆ m_incoming_connections

◆ m_io_context

◆ m_log_opts

◆ m_mutex

◆ m_post_fd

◆ m_task_set

◆ m_thread_id

◆ m_wait_fd