Sane C++ Libraries: SC::AsyncEventLoop Struct Reference (original) (raw)

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](Async%5F8h%5Fsource.html)>

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.

See also

AsyncEventLoopMonitor can be used to integrate AsyncEventLoop with a GUI event loop

Basic lifetime for an event loop is:

AsyncEventLoop eventLoop;

SC_TRY(eventLoop.create());

SC_TRY(eventLoop.close());

◆ associateExternallyCreatedFileDescriptor()

Associates a previously created File Descriptor with the eventLoop.

◆ associateExternallyCreatedSocket()

Associates a previously created TCP / UDP socket with the eventLoop.

◆ blockingPoll()

Blocks until at least one event happens, ensuring forward progress, without executing completions.

It's one of the three building blocks of AsyncEventLoop::runOnce allowing co-operation of AsyncEventLoop within another event loop (for example a GUI event loop or another IO event loop).

One possible example of such integration with a GUI event loop could:

• Call AsyncEventLoop::submitRequests on the GUI thread to queue some requests
• Call AsyncEventLoop::blockingPoll on a secondary thread, storying AsyncKernelEvents
• Wake up the GUI event loop from the secondary thread after AsyncEventLoop::blockingPoll returns
• Call AsyncEventLoop:dispatchCompletions on the GUI event loop to dispatch callbacks on GUI thread
• Repeat all steps

Waiting on requests blocks the current thread with 0% CPU utilization.

Parameters

See also

AsyncEventLoop::submitRequests sends async requests to kernel before calling blockingPoll

AsyncEventLoop::dispatchCompletions invokes callbacks associated with kernel events after blockingPoll

AsyncEventLoop::setListeners sets function called before and after entering kernel poll

◆ clearSequence()

Clears the sequence.

◆ close()

Closes the event loop kernel object.

◆ create()

Creates the event loop kernel object.

◆ createAsyncTCPSocket()

Creates an async TCP (IPV4 / IPV6) socket registered with the eventLoop.

◆ createAsyncUDPSocket()

Creates an async UCP (IPV4 / IPV6) socket registered with the eventLoop.

◆ dispatchCompletions()

Invokes completions for the AsyncKernelEvents collected by a call to AsyncEventLoop::blockingPoll.

This is typically done when user wants to pool for events on a thread (calling AsyncEventLoop::blockingPoll) and dispatch the callbacks on another thread (calling AsyncEventLoop::dispatchCompletions). The typical example would be integrating AsyncEventLoop with a GUI event loop.

See also

AsyncEventLoop::blockingPoll for a description on how to integrate AsyncEventLoop with another event loop

◆ enumerateRequests()

Enumerates all requests objects associated with this loop.

◆ excludeFromActiveCount()

Excludes the request from active handles count (to avoid it keeping event loop alive)

◆ findEarliestLoopTimeout()

◆ getLoopTime()

Get Loop time (monotonic)

◆ getNumberOfActiveRequests()

Obtain the total number of active requests.

◆ getNumberOfSubmittedRequests()

Obtain the total number of submitted requests.

◆ includeInActiveCount()

Reverses the effect of excludeFromActiveCount for the request.

◆ interrupt()

Interrupts the event loop even if it has active request on it.

◆ isExcludedFromActiveCount()

Checks if excludeFromActiveCount() has been called on the given request.

◆ isInitialized()

Returns true if create has been already called (successfully)

◆ needsThreadPoolForFileOperations()

Returns true if backend needs a thread pool for non-blocking fs operations (anything but io_uring basically)

◆ removeAllAssociationsFor() [1/2]

Removes association of a File Descriptor with any event loop.

◆ removeAllAssociationsFor() [2/2]

Removes association of a TCP Socket with any event loop.

◆ run()

Blocks until there are no more active queued requests, dispatching all completions.

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 kernel events blocks the current thread with 0% CPU utilization.

See also

AsyncEventLoop::blockingPoll to integrate the loop with a GUI event loop

◆ runNoWait()

Process active requests if any, dispatching their completions, 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.

See also

AsyncEventLoop::blockingPoll to integrate the loop with a GUI event loop

◆ runOnce()

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

It's useful for application where it's needed to run some idle work after every IO event. Waiting on requests blocks the current thread with 0% CPU utilization.

This function is a shortcut invoking async event loop building blocks:

• AsyncEventLoop::submitRequests
• AsyncEventLoop::blockingPoll
• AsyncEventLoop::dispatchCompletions
  See also
  AsyncEventLoop::blockingPoll for a description on how to integrate AsyncEventLoop with another event loop

◆ setListeners()

Sets reference to listeners that will signal different events in loop lifetime.

Note

The structure pointed by this pointer must be valid throughout loop lifetime

◆ start()

Queues an async request request that has been correctly setup.

Note

The request will be validated immediately and activated during next event loop cycle

◆ submitRequests()

◆ tryLoadingLiburing()

Check if liburing is loadable (only on Linux)

Returns

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

◆ updateTime()

Updates loop time to "now".

◆ wakeUpFromExternalThread() [1/2]

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

◆ wakeUpFromExternalThread() [2/2]

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