Async

🟨 Async I/O (files, sockets, timers, processes, fs events, threads wake-up) (see Async for more details) Async is a multi-platform / event-driven asynchronous I/O library. More...

Classes
struct	SC::AsyncRequest
	Base class for all async requests, holding state and type. More...
struct	SC::AsyncCompletionData
	Empty base struct for all AsyncRequest-derived CompletionData (internal) structs. More...
struct	SC::AsyncResult
	Base class for all async results (argument of completion callbacks). More...
struct	SC::AsyncResultOf< T, C >
	Helper holding CompletionData for a specific AsyncRequest-derived class. More...
struct	SC::AsyncTask
	Holds (reference to) a SC::ThreadPool and SC::ThreadPool::Task to execute an SC::AsyncRequest in a background thread This object lifetime is the same as the SC::AsyncRequest it's associated with, like SC::AsyncFileRead or SC::AsyncFileWrite. More...
struct	SC::AsyncTaskOf< AsyncType >
	Create an async Callback result for a given AsyncRequest-derived class. More...
struct	SC::AsyncLoopTimeout
	Starts a Timeout that is invoked only once after expiration (relative) time has passed. More...
struct	SC::AsyncLoopWakeUp
	Starts a wake-up operation, allowing threads to execute callbacks on loop thread. More...
struct	SC::AsyncLoopWork
	Executes work in a thread pool and then invokes a callback on the event loop thread. More...
struct	SC::AsyncProcessExit
	Starts monitoring a process, notifying about its termination. More...
struct	SC::AsyncSocketAccept
	Starts a socket accept operation, obtaining a new socket from a listening socket. More...
struct	SC::AsyncSocketConnect
	Starts a socket connect operation, connecting to a remote endpoint. More...
struct	SC::AsyncSocketSend
	Starts a socket send operation, sending bytes to a remote endpoint. More...
struct	SC::AsyncSocketReceive
	Starts a socket receive operation, receiving bytes from a remote endpoint. More...
struct	SC::AsyncSocketClose
	Starts a socket close operation. More...
struct	SC::AsyncFileRead
	Starts a file read operation, reading bytes from a file (or pipe). More...
struct	SC::AsyncFileWrite
	Starts a file write operation, writing bytes to a file (or pipe). More...
struct	SC::AsyncFileClose
	Starts a file close operation, closing the OS file descriptor. More...
struct	SC::AsyncFilePoll
	Starts an handle polling operation. More...
struct	SC::AsyncKernelEvents
	Allows user to supply a block of memory that will store kernel I/O events retrieved from AsyncEventLoop::runOnce. More...
struct	SC::AsyncEventLoop
	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...
struct	SC::AsyncEventLoopMonitor
	Monitors Async I/O events from a background thread using a blocking kernel function (no CPU usage on idle). More...

Detailed Description

🟨 Async I/O (files, sockets, timers, processes, fs events, threads wake-up) (see Async for more details) Async is a multi-platform / event-driven asynchronous I/O library.

It exposes async programming model for common IO operations like reading / writing to / from a file or tcp socket.

Synchronous I/O operations could block the current thread of execution for an undefined amount of time, making it difficult to scale an application to a large number of concurrent operations, or to coexist with other even loop, like for example a GUI event loop. Such async programming model uses a common pattern, where the call fills an AsyncRequest with the required data. The AsyncRequest is added to an AsyncEventLoop that will queue the request to some low level OS IO queue. The event loop can then monitor all the requests in a single call to SC::AsyncEventLoop::run, SC::AsyncEventLoop::runOnce or SC::AsyncEventLoop::runNoWait. These three different run methods cover different integration use cases of the event loop inside of an applications.

The kernel Async API used on each operating systems are the following:

• IOCP on Windows
• kqueue on macOS
• epoll on Linux
• io_uring on Linux (dynamically loading liburing)

Note

If liburing is not available on the system, the library will transparently fallback to epoll.

If an async operation is not supported by the OS, the caller can provide a SC::ThreadPool to run it on a thread. See SC::AsyncFileRead / SC::AsyncFileWrite for an example.