SC::AsyncEventLoop Struct Reference

Asynchronous I/O (files, sockets, timers, processes, fs events, threads wake-up) (see Async) AsyncEventLoop pushes all AsyncRequest derived classes to I/O queues in the OS. More...

#include <Async.h>

Classes
struct	Options
	Options given to AsyncEventLoop::create. More...

Public Types
using	PrivateOpaque = OpaqueObject< PrivateDefinition >
using	InternalOpaque = OpaqueObject< InternalDefinition >

Public Member Functions
Result	create (Options options=Options())
	Creates the event loop kernel object. More...
Result	close ()
	Closes the event loop kernel object. More...
Result	run ()
	Blocks until there are no more active queued requests. More...
Result	runOnce ()
	Blocks until at least one request proceeds, ensuring forward progress. More...
Result	runNoWait ()
	Process active requests if they exist or returns immediately without blocking. More...
Result	wakeUpFromExternalThread (AsyncLoopWakeUp &wakeUp)
	Wake up the event loop from a thread different than the one where run() is called (and potentially blocked). More...
Result	wakeUpFromExternalThread ()
	Wake up the event loop from a thread different than the one where run() is called (and potentially blocked) More...
Result	createAsyncTCPSocket (SocketFlags::AddressFamily family, SocketDescriptor &outDescriptor)
	Helper to creates a TCP socket with AsyncRequest flags of the given family (IPV4 / IPV6). More...
Result	associateExternallyCreatedTCPSocket (SocketDescriptor &outDescriptor)
	Associates a TCP Socket created externally (without using createAsyncTCPSocket) with the eventLoop. More...
Result	associateExternallyCreatedFileDescriptor (FileDescriptor &outDescriptor)
	Associates a File descriptor created externally with the eventLoop. More...
Time::HighResolutionCounter	getLoopTime () const
	Get Loop time. More...

Static Public Member Functions
static bool	tryLoadingLiburing ()
	Check if liburing is loadable (only on Linux) More...

Friends
struct	AsyncRequest
struct	AsyncFileWrite
struct	AsyncFileRead

Detailed Description

Asynchronous I/O (files, sockets, timers, processes, fs events, threads wake-up) (see Async) AsyncEventLoop pushes all AsyncRequest derived classes to I/O queues in the OS.

Basic lifetime for an event loop is:

AsyncEventLoop eventLoop;
SC_TRY(eventLoop.create()); // Create OS specific queue handles
// ...
// Add all needed AsyncRequest
// ...
SC_TRY(eventLoop.run());
// ...
// Here all AsyncRequest have either finished or have been stopped
// ...
SC_TRY(eventLoop.close()); // Free OS specific queue handles

Member Function Documentation

associateExternallyCreatedFileDescriptor()

Result SC::AsyncEventLoop::associateExternallyCreatedFileDescriptor

(

FileDescriptor &

outDescriptor

)

Associates a File descriptor created externally with the eventLoop.

associateExternallyCreatedTCPSocket()

Result SC::AsyncEventLoop::associateExternallyCreatedTCPSocket

(

SocketDescriptor &

outDescriptor

)

Associates a TCP Socket created externally (without using createAsyncTCPSocket) with the eventLoop.

close()

Result SC::AsyncEventLoop::close

(

)

Closes the event loop kernel object.

create()

Result SC::AsyncEventLoop::create

(

Options

options = Options()

)

Creates the event loop kernel object.

createAsyncTCPSocket()

Result SC::AsyncEventLoop::createAsyncTCPSocket	(	SocketFlags::AddressFamily	family,
		SocketDescriptor &	outDescriptor
	)

Helper to creates a TCP socket with AsyncRequest flags of the given family (IPV4 / IPV6).

It also automatically registers the socket with the eventLoop (associateExternallyCreatedTCPSocket)

getLoopTime()

Time::HighResolutionCounter SC::AsyncEventLoop::getLoopTime

(

)

const

Get Loop time.

run()

Result SC::AsyncEventLoop::run

(

)

Blocks until there are no more active queued requests.

It's useful for applications where the eventLoop is the only (or the main) loop. One example could be a console based app doing socket IO or a web server. Waiting on requests blocks the current thread with 0% CPU utilization.

runNoWait()

Result SC::AsyncEventLoop::runNoWait

(

)

Process active requests if they exist or returns immediately without blocking.

It's useful for game-like applications where the event loop runs every frame and one would like to check and dispatch its I/O callbacks in-between frames. This call allows poll-checking I/O without blocking.

runOnce()

Result SC::AsyncEventLoop::runOnce

(

)

Blocks until at least one request proceeds, ensuring forward progress.

It's useful for applications where the eventLoop events needs to be interleaved with other work. For example one possible way of integrating with a UI event loop could be to schedule a recurrent timeout timer every 1/60 seconds where calling GUI event loop updates every 60 seconds, blocking for I/O for the remaining time. Waiting on requests blocks the current thread with 0% CPU utilization.

tryLoadingLiburing()

static bool SC::AsyncEventLoop::tryLoadingLiburing ( )

static

Check if liburing is loadable (only on Linux)

Returns

true if liburing has been loaded, false otherwise (and on any non-Linux os)

wakeUpFromExternalThread() [1/2]

Result SC::AsyncEventLoop::wakeUpFromExternalThread

(

)

Wake up the event loop from a thread different than the one where run() is called (and potentially blocked)

wakeUpFromExternalThread() [2/2]

Result SC::AsyncEventLoop::wakeUpFromExternalThread

(

AsyncLoopWakeUp &

wakeUp

)

Wake up the event loop from a thread different than the one where run() is called (and potentially blocked).

The parameter is an AsyncLoopWakeUp that must have been previously started (with AsyncLoopWakeUp::start).

---

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

• Async.h