Note: Check Async Streams for an higher level construct when streaming data; Check Await for the C++20 coroutine layer that wraps AsyncEventLoop with co_await syntax while preserving the same request lifetime expectations. It currently covers a small but useful subset of timers, sockets, loop wake-ups, files, file readiness, selected filesystem operations, process exit, signals, background work, child tasks, task groups, cancellation, and timeouts.; Await keeps the same platform caveats as Async: POSIX file readiness is exposed directly, while Windows file readiness for normal file or pipe handles currently fails fast at the Await layer instead of pretending to be portable. File and filesystem operations that need blocking work use caller-provided ThreadPool storage.; Long-lived callback streams such as FileSystemWatcher should stay callback-style or use an explicit caller-owned adapter with bounded event storage. Await intentionally does not model watcher streams as direct AwaitEventLoop methods.

Dependencies

Dependencies: File, FileSystem, Socket, Threading
All dependencies: File, FileSystem, Socket, Threading

Dependency Graph

Features

This is the list of supported async operations:

Async Operation	Description
AsyncSocketConnect	Starts a socket connect operation, connecting to a remote endpoint.
AsyncSocketAccept	Starts a socket accept operation, obtaining a new socket from a listening socket.
AsyncSocketSend	Starts a socket send operation, sending bytes to a remote endpoint.
AsyncSocketReceive	Starts a socket receive operation, receiving bytes from a remote endpoint.
AsyncSocketSendTo	Starts an unconnected socket send to operation, sending bytes to a remote endpoint.
AsyncSocketReceiveFrom	Starts an unconnected socket receive from operation, receiving bytes from a remote endpoint.
AsyncFileRead	Starts a file read operation, reading bytes from a file (or pipe).
AsyncFileWrite	Starts a file write operation, writing bytes to a file (or pipe).
AsyncLoopTimeout	Starts a Timeout that is invoked only once after expiration (relative) time has passed.
AsyncLoopWakeUp	Starts a wake-up operation, allowing threads to execute callbacks on loop thread.
AsyncLoopWork	Executes work in a thread pool and then invokes a callback on the event loop thread.
AsyncProcessExit	Starts monitoring a process, notifying about its termination.
AsyncFileReadiness	Starts a file descriptor readiness operation.
AsyncExternalCompletion	Integrates externally-submitted completion based operations with AsyncEventLoop.
AsyncSequence	Execute AsyncRequests serially, by submitting the next one after the previous one is completed.
AsyncFileSystemOperation	Starts an asynchronous file system operation (open, close, read, write, sendFile, stat, lstat, fstat, etc.) Some operations need a file path and others need a file descriptor.
AsyncSignal	Starts monitoring a signal, notifying about its reception.

Details

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
io_uring on Linux
epoll on Linux

Note: If direct io_uring setup is not available on the system, the library will fallback to epoll.

If an operation may require blocking work on a backend, the caller must provide a SC::ThreadPool through the operation-specific API. Backends that can perform the operation natively, such as Linux io_uring file I/O, prefer native async by default. Pass SC::AsyncThreadPoolMode::ForceThreadPool to force using the supplied pool.

Status

🟨 MVP
This is usable but needs some more testing and a few more features.

Videos

This is the list of videos that have been recorded showing some of the internal thoughts that have been going into this library:

Blog

Some relevant blog posts are:

Description

An async operation is struct derived from AsyncRequest asking for some I/O to be done made to the OS.
Every async operation has an associated callback that is invoked when the request is fulfilled. If the start function returns a valid (non error) Return code, then the user callback will be called both in case of success and in case of any error.
If the function returns an invalid Return code or if the operation is manually cancelled with SC::AsyncRequest::stop, then the user callback will not be called.

Note

The memory address of all AsyncRequest derived objects must be stable until user callback is executed.

If request is not re-activated (i.e. result.reactivateRequest(true) is NOT called) then the async request can be freed as soon as the user callback is called (even inside the callback itself).
If request is re-activated (i.e. result.reactivateRequest(true) is called) then the async cannot be freed as it's still in use.

Some implementation details: SC::AsyncRequest::state dictates the lifetime of the async request according to a state machine.

Regular Lifetime of an Async request (called just async in the paragraph below):

An async that has been started, will be pushed in the submission queue with state == State::Setup.
Inside stageSubmission a started async will be do the one time setup (with setupAsync)
Inside stageSubmission a Setup or Submitting async will be activated (with activateAsync)
If activateAsync is successful, the async becomes state == State::Active.
- When this happens, the async is either tracked by the kernel or in one of the linked lists like activeLoopWakeUps
The Active async can become completed, when the kernel signals its completion (or readiness...):
- [default] -> Async is complete and it will be teardown and freed (state == State::Free)
- result.reactivateRequest(true) -> Async gets submitted again (state == State::Submitting) (3.)

Cancellation of an async: An async can be cancelled at any time:

Async not yet submitted in State::Setup --> it just gets removed from the submission queue
Async in submission queue but already setup --> it will receive a teardownAsync
Async in Active state (so after setupAsync and activateAsync) --> will receive cancelAsync and teardownAsync

Any other case is considered an error (trying to cancel an async already being cancelled or being teardown).

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.

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()); // 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

Run modes

Event loop can be run in different ways to allow integrated it in multiple ways in applications.

Run mode

Description

SC::AsyncEventLoop::run

Blocks until there are no more counted active, submitted, or cancelling requests, dispatching 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. AsyncEventLoop::interrupt makes this function return before active work has drained. Requests excluded with AsyncEventLoop::excludeFromActiveCount do not keep this function alive.

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

SC::AsyncEventLoop::runOnce

Blocks until at least one request proceeds, ensuring forward progress, dispatching ready 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

SC::AsyncEventLoop::runNoWait

Process ready 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

Alternatively user can explicitly use three methods to submit, poll and dispatch events. This is very useful to integrate the event loop into applications with other event loops (for example GUI applications).

Run mode Description

SC::AsyncEventLoop::submitRequests

Submits all queued async requests without running user callbacks.

An AsyncRequest becomes queued after user calls its specific AsyncRequest::start method.

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

SC::AsyncEventLoop::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). User callbacks are not invoked by this function; they run when AsyncEventLoop::dispatchCompletions is called. AsyncEventLoopListeners callbacks, if installed, are invoked around this blocking poll.

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, storing 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

kernelEvents Mandatory parameter to store kernel IO events WITHOUT running their completions. In that case user is expected to run completions passing it to AsyncEventLoop::dispatchCompletions.

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

SC::AsyncEventLoop::dispatchCompletions

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

This is typically done when user wants to poll for events on a thread (calling AsyncEventLoop::blockingPoll) and dispatch the callbacks on another thread (calling AsyncEventLoop::dispatchCompletions). User callbacks run on the thread calling this function. 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

AsyncEventLoopMonitor

Monitors Async I/O events from a background thread using a blocking kernel function (no CPU usage on idle).

AsyncEventLoopMonitor makes it easy to integrate AsyncEventLoop within a GUI event loop or another I/O event loop. This pattern avoids constantly polling the kernel, using virtually 0% of CPU time when waiting for events.

Functions

Description

SC::AsyncEventLoopMonitor::startMonitoring

Queue all async requests submissions and start monitoring loop events on a background thread.

On the background thread AsyncEventLoop::blockingPoll will block (with 0% CPU usage) and return only when it will be informed by the kernel of some new events. Immediately after AsyncEventLoopMonitor::onNewEventsAvailable will be called (on the background thread). In the code handler associated with this event, the user/caller should inform its main thread to call AsyncEventLoopMonitor::stopMonitoringAndDispatchCompletions.

SC::AsyncEventLoopMonitor::stopMonitoringAndDispatchCompletions

Stops monitoring events on the background thread and dispatches callbacks for completed requests.

This is typically called by the user of this class on the main thread or in general on the thread where the event loop that coordinates the application lives (GUI thread typically or another I/O Event Loop thread).

Note: In some cases this method will also immediately submit new requests that have been queued by callbacks.

AsyncLoopTimeout

Starts a Timeout that is invoked only once after expiration (relative) time has passed.

Note: For a periodic timeout, call AsyncLoopTimeout::Result::reactivateRequest(true) in the completion callback

// Create a timeout that will be called after 200 milliseconds
// AsyncLoopTimeout must be valid until callback is called
AsyncLoopTimeout timeout;
timeout.callback = [&](AsyncLoopTimeout::Result& res)
{
    console.print("My timeout has been called!");
    if (someCondition) // Optionally re-activate the timeout if needed
    {
        // Schedule the timeout callback to fire again 100 ms from now
        res.getAsync().relativeTimeout = Time::Milliseconds(100);
        res.reactivateRequest(true);
    }
};
// Start the timeout, that will be called 200 ms from now
SC_TRY(timeout.start(eventLoop, 200_ms));

AsyncLoopWakeUp

Starts a wake-up operation, allowing threads to execute callbacks on loop thread.

SC::AsyncLoopWakeUp::callback will be invoked on the thread running SC::AsyncEventLoop::run (or its variations) after SC::AsyncLoopWakeUp::wakeUp has been called.

Note: There is no guarantee that after calling AsyncLoopWakeUp::start the callback has actually finished execution. An optional SC::EventObject passed to SC::AsyncLoopWakeUp::start can be used for synchronization. By default repeated pending wakeUp() calls are coalesced like libuv uv_async_t. Set AsyncLoopWakeUpOptions::coalesce to false to receive one callback per pending wake-up instead.; AsyncLoopWakeUp stays active only until its callback runs. To continue receiving wake-ups after a callback, call AsyncLoopWakeUp::Result::reactivateRequest(true) from inside the callback. Persistent async-send wrappers should reactivate from the callback before returning. Calling wakeUp() after the request is free is tolerated for cross-thread race handling, but should not be used as an application-level notification mechanism.

// Assuming an already created (and running) AsyncEventLoop named eventLoop
// ...
// This code runs on some different thread from the one calling SC::AsyncEventLoop::run.
// The callback is invoked from the thread calling SC::AsyncEventLoop::run
AsyncLoopWakeUp wakeUp; // Memory lifetime must be valid until callback is called
wakeUp.callback = [&](AsyncLoopWakeUp::Result& result)
{
    console.print("My wakeUp has been called!");
    result.reactivateRequest(true); // To allow waking-up again later
};
SC_TRY(wakeUp.start(eventLoop));

An EventObject can be wait-ed to synchronize further actions from the thread invoking the wake up request, ensuring that the callback has finished its execution.

// Assuming an already created (and running) AsyncEventLoop named eventLoop
// ...
// This code runs on some different thread from the one calling SC::AsyncEventLoop::run.
// The callback is invoked from the thread calling SC::AsyncEventLoop::run
AsyncLoopWakeUp wakeUpWaiting; // Memory lifetime must be valid until callback is called
wakeUpWaiting.callback = [&](AsyncLoopWakeUp::Result& result)
{
    console.print("My wakeUp has been called!");
    result.reactivateRequest(true); // To allow waking-up it again later
};
EventObject eventObject;
SC_TRY(wakeUpWaiting.start(eventLoop, eventObject));
eventObject.wait(); // Wait until callback has been fully run inside event loop thread
// From here on we know for sure that callback has been called

AsyncLoopWork

Executes work in a thread pool and then invokes a callback on the event loop thread.

AsyncLoopWork::work is invoked on one of the thread supplied by the ThreadPool passed during AsyncLoopWork::start. AsyncLoopWork::callback will be called as a completion, on the event loop thread AFTER work callback is finished.

    // This test creates a thread pool with 4 thread and 16 AsyncLoopWork.
    // All the 16 AsyncLoopWork are scheduled to do some work on a background thread.
    // After work is done, their respective after-work callback is invoked on the event loop thread.
 
    static constexpr int NUM_THREADS = 4;
    static constexpr int NUM_WORKS   = NUM_THREADS * NUM_THREADS;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create());
 
    AsyncLoopWork works[NUM_WORKS];
 
    int         numAfterWorkCallbackCalls = 0;
    Atomic<int> numWorkCallbackCalls      = 0;
 
    for (int idx = 0; idx < NUM_WORKS; ++idx)
    {
        works[idx].work = [&]
        {
            // This work callback is called on some random threadPool thread
            Thread::Sleep(50);                 // Execute some work on the thread
            numWorkCallbackCalls.fetch_add(1); // Atomically increment this counter
            return Result(true);
        };
        works[idx].callback = [&](AsyncLoopWork::Result&)
        {
            // This after-work callback is invoked on the event loop thread.
            // More precisely this runs on the thread calling eventLoop.run().
            numAfterWorkCallbackCalls++; // No need for atomics here, callback is run inside loop thread
        };
        // Must always call setThreadPool at least once before start
        SC_TEST_EXPECT(works[idx].setThreadPool(threadPool));
        SC_TEST_EXPECT(works[idx].start(eventLoop));
    }
    int numRequests = 0;
    eventLoop.enumerateRequests([&](AsyncRequest&) { numRequests++; });
    SC_TEST_EXPECT(eventLoop.run());
    SC_TEST_EXPECT(numRequests == NUM_WORKS);
 
    // Check that callbacks have been actually called
    SC_TEST_EXPECT(numWorkCallbackCalls.load() == NUM_WORKS);
    SC_TEST_EXPECT(numAfterWorkCallbackCalls == NUM_WORKS);

AsyncProcessExit

Starts monitoring a process, notifying about its termination.

Process library can be used to start a process and obtain the native process handle.

// Assuming an already created (and running) AsyncEventLoop named eventLoop
// ...
Process process;
SC_TRY(process.launch({"executable", "--parameter"}));
AsyncProcessExit processExit; //  Memory lifetime must be valid until callback is called
processExit.callback = [&](AsyncProcessExit::Result& res)
{
    int exitStatus = -1;
    if(res.get(exitStatus))
    {
        console.print("Process Exit status = {}", exitStatus);
    }
};
SC_TRY(processExit.start(eventLoop, process.handle));

AsyncSignal

Starts monitoring a signal, notifying about its reception.

AsyncSignal follows the base AsyncRequest lifecycle: after a delivered signal, the request is completed unless the callback calls Result::reactivateRequest(true). AsyncSignalOptions::mode and coalesce are kept as explicit policy fields for future backend-parity work, but portable code should not rely on them for automatic reactivation.

On POSIX systems, signals like SIGINT, SIGTERM, SIGHUP are supported. On Windows, console control signals CTRL_C_EVENT, CTRL_BREAK_EVENT, and CTRL_CLOSE_EVENT are mapped to SIGINT (2), signal 21, and SIGTERM (15) respectively.

Signal watcher capabilities:

one watcher for a given signal is supported on all backends.
multiple different signals on the same loop are supported on all backends.
multiple watchers for the same signal on Windows are supported through the process-wide console signal registry.
multiple POSIX watchers for the same signal are backend-dependent and should not be used as a portable fanout mechanism. Prefer one AsyncSignal per process signal and fan out from that callback when portable behavior matters.

// Assuming an already created (and running) AsyncEventLoop named eventLoop
// ...
AsyncSignal asyncSignal;
asyncSignal.callback = [&](AsyncSignal::Result& res)
{
    console.print("Signal {} received {} times", res.completionData.signalNumber, res.completionData.deliveryCount);
};
// On Windows, SIGINT (2) -> CTRL_C_EVENT, 21 -> CTRL_BREAK_EVENT, SIGTERM (15) -> CTRL_CLOSE_EVENT
SC_TRY(asyncSignal.start(eventLoop, SIGINT));

AsyncSocketAccept

Starts a socket accept operation, obtaining a new socket from a listening socket.

The callback is called with a new socket connected to the given listening endpoint will be returned.
Socket library can be used to create a Socket but the socket should be created with SC::SocketFlags::NonBlocking and associated to the event loop with SC::AsyncEventLoop::associateExternallyCreatedSocket.
Alternatively SC::AsyncEventLoop::createAsyncTCPSocket creates and associates the socket to the loop.

Note: To continue accepting new socket SC::AsyncResult::reactivateRequest must be called.

// Assuming an already created (and running) AsyncEventLoop named eventLoop
// ...
// Create a listening socket
constexpr uint32_t numWaitingConnections = 2;
SocketDescriptor   serverSocket;
uint16_t           tcpPort = 5050;
SocketIPAddress    nativeAddress;
SC_TRY(nativeAddress.fromAddressPort("127.0.0.1", tcpPort));
SC_TRY(eventLoop.createAsyncTCPSocket(nativeAddress.getAddressFamily(), serverSocket));
SocketServer server(serverSocket);
SC_TRY(server.bind(nativeAddress));
SC_TRY(server.listen(numWaitingConnections));
// Accept connect for new clients
AsyncSocketAccept accept;
accept.callback = [&](AsyncSocketAccept::Result& res)
{
    SocketDescriptor client;
    if(res.moveTo(client))
    {
        // ...do something with new client
        console.printLine("New client connected!");
        res.reactivateRequest(true); // We want to receive more clients
    }
};
SC_TRY(accept.start(eventLoop, serverSocket));
// ... at some later point
// Stop accepting new clients
SC_TRY(accept.stop(eventLoop));

AsyncSocketConnect

Starts a socket connect operation, connecting to a remote endpoint.

Callback will be called when the given socket is connected to ipAddress.
Socket library can be used to create a Socket but the socket should be created with SC::SocketFlags::NonBlocking and associated to the event loop with SC::AsyncEventLoop::associateExternallyCreatedSocket.
Alternatively SC::AsyncEventLoop::createAsyncTCPSocket creates and associates the socket to the loop.

// Assuming an already created (and running) AsyncEventLoop named eventLoop
// ...
SocketIPAddress localHost;
SC_TRY(localHost.fromAddressPort("127.0.0.1", 5050)); // Connect to some host and port
AsyncSocketConnect connect;
SocketDescriptor   client;
SC_TRY(eventLoop.createAsyncTCPSocket(localHost.getAddressFamily(), client));
connect.callback = [&](AsyncSocketConnect::Result& res)
{
    if (res.isValid())
    {
        // Do something with client that is now connected
        console.printLine("Client connected");
    }
};
SC_TRY(connect.start(eventLoop, client, localHost));

AsyncSocketSend

Starts a socket send operation, sending bytes to a remote endpoint.

Callback will be called when the given socket is ready to send more data.
Socket library can be used to create a Socket but the socket should be created with SC::SocketFlags::NonBlocking and associated to the event loop with SC::AsyncEventLoop::associateExternallyCreatedSocket or though AsyncSocketAccept.
Alternatively SC::AsyncEventLoop::createAsyncTCPSocket creates and associates the socket to the loop.

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// and a connected or accepted socket named `client`
// ...
const char sendBuffer[] = {123, 111};
 
// The memory pointed by the span must be valid until callback is called
Span<const char> sendData = {sendBuffer, sizeof(sendBuffer)};
 
AsyncSocketSend sendAsync;
sendAsync.callback = [&](AsyncSocketSend::Result& res)
{
    if(res.isValid())
    {
        // Now we could free the data pointed by span and queue new data
        console.printLine("Ready to send more data");
    }
};
 
SC_TRY(sendAsync.start(eventLoop, client, sendData));
// Vectorized writes: use proper start overload or set
// AsyncSocketSend::buffers and AsyncSocketSend::singleBuffer = false
 

AsyncSocketReceive

Starts a socket receive operation, receiving bytes from a remote endpoint.

Callback will be called when some data is read from socket.
Socket library can be used to create a Socket but the socket should be created with SC::SocketFlags::NonBlocking and associated to the event loop with SC::AsyncEventLoop::associateExternallyCreatedSocket or though AsyncSocketAccept.
Alternatively SC::AsyncEventLoop::createAsyncTCPSocket creates and associates the socket to the loop.

Additional notes:

SC::AsyncSocketReceive::CompletionData::disconnected will be set to true when client disconnects

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// and an unconnected socket named `client`
// ...
char receivedData[100] = {0}; // A buffer to hold data read from the socket
AsyncSocketReceive receiveAsync;
receiveAsync.callback = [&](AsyncSocketReceive::Result& res)
{
    Span<char> readData;
    if(res.get(readData))
    {
        if(res.completionData.disconnected)
        {
            // Last callback invocation is done when the other side of the socket
            // has disconnected:
            // - completionData.disconnected is == true
            // - readData.sizeInBytes() is == 0
            console.print("Client disconnected");
        }
        else
        {
            // readData is a slice of receivedData with the received bytes
            console.print("{} bytes have been read", readData.sizeInBytes());
            
            // IMPORTANT: Reactivate the request to receive more data
            res.reactivateRequest(true);
        }
    }
    else
    {
        // Some error occurred, check res.returnCode
    }
};
SC_TRY(receiveAsync.start(eventLoop, client, {receivedData, sizeof(receivedData)}));

AsyncSocketSendTo

Starts an unconnected socket send to operation, sending bytes to a remote endpoint.

Callback will be called when the given socket is ready to send more data.
Typical use case is to send data to an unconnected UDP socket.
Socket library can be used to create a Socket but the socket should be created with SC::SocketFlags::NonBlocking and associated to the event loop with SC::AsyncEventLoop::associateExternallyCreatedSocket or though AsyncSocketAccept.
Alternatively SC::AsyncEventLoop::createAsyncUDPSocket creates and associates the socket to the loop.

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// and a connected or accepted socket named `client`
// ...
SocketIPAddress destinationAddress;
SC_TRY(destinationAddress.fromAddressPort("127.0.0.1", 5051)); // Connect to localhost on port
const char sendBuffer[] = {123, 111};
 
// The memory pointed by the span must be valid until callback is called
Span<const char> sendData = {sendBuffer, sizeof(sendBuffer)};
 
AsyncSocketSendTo sendAsync;
sendAsync.callback = [&](AsyncSocketSendTo::Result& res)
{
    if(res.isValid())
    {
        // Now we could free the data pointed by span and queue new data
        console.printLine("Ready to send more data");
    }
};
// Assuming client is an unconnected UDP Socket
SC_TRY(sendAsync.start(eventLoop, client, destinationAddress, sendData));
// Vectorized writes: use proper start overload or set
// AsyncSocketSend::buffers and AsyncSocketSend::singleBuffer = false
 

AsyncSocketReceiveFrom

Starts an unconnected socket receive from operation, receiving bytes from a remote endpoint.

Callback will be called when some data is read from socket.
Typical use case is to receive data from an unconnected UDP socket.
Socket library can be used to create a Socket but the socket should be created with SC::SocketFlags::NonBlocking and associated to the event loop with SC::AsyncEventLoop::associateExternallyCreatedSocket or though AsyncSocketAccept.
Alternatively SC::AsyncEventLoop::createAsyncUDPSocket creates and associates the socket to the loop.

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// ...
char receivedData[100] = {0}; // A buffer to hold data read from the socket
AsyncSocketReceiveFrom receiveAsync;
receiveAsync.callback = [&](AsyncSocketReceive::Result& res)
{
    Span<char> readData;
    if(res.get(readData))
    {
        if(res.completionData.disconnected)
        {
            // Last callback invocation done when other side of the socket has disconnected.
            // - completionData.disconnected is == true
            // - readData.sizeInBytes() is == 0
            console.print("Client disconnected");
        }
        else
        {
            // readData is a slice of receivedData with the received bytes
            console.print("{} bytes have been read", readData.sizeInBytes());
            
            // Get the source address / port of the received data
            SocketIPAddress sourceAddress = res.getSourceAddress();
            SocketIPAddress::AsciiBuffer buffer;
            StringView formattedAddress;
            (void)sourceAddress.toString(buffer, formattedAddress);
            console.print("Source address: {}:{}", formattedAddress, sourceAddress.getPort());
            
            // IMPORTANT: Reactivate the request to receive more data
            res.reactivateRequest(true);
        }
    }
    else
    {
        // Some error occurred, check res.returnCode
    }
};
// Assuming client is an unconnected UDP Socket
SC_TRY(receiveAsync.start(eventLoop, client, {receivedData, sizeof(receivedData)}));

AsyncFileRead

Starts a file read operation, reading bytes from a file (or pipe).

Callback will be called when the data read from the file (or pipe) is available.
Call AsyncRequest::executeOn to set a thread pool if this is a buffered file and not a pipe. This is important on APIs with blocking behaviour on buffered file I/O (all APIs except io_uring).

File library can be used to open the file and obtain a file (or pipe) descriptor handle.

Note: Pipes or files opened using Posix O_DIRECT or Windows FILE_FLAG_WRITE_THROUGH & FILE_FLAG_NO_BUFFERING should instead avoid using the Task parameter for best performance.

When not using the Task remember to:

Open the file descriptor for non-blocking IO (SC::File::OpenOptions::blocking == false)
Call SC::AsyncEventLoop::associateExternallyCreatedFileDescriptor on the file descriptor

Additional notes:

When reactivating the AsyncRequest, remember to increment the offset (SC::AsyncFileRead::offset)
SC::AsyncFileRead::CompletionData::endOfFile signals end of file reached
io_uring backend will not use thread pool by default because that API allows proper async file read/writes
Pass AsyncThreadPoolMode::ForceThreadPool to executeOn to force using the supplied thread pool

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// ...
 
// Assuming an already created threadPool named `eventLoop
// ...
 
// Open the file
FileDescriptor fd;
FileOpen openMode;
openMode.mode = FileOpen::Read;
openMode.blocking = true; // AsyncFileRead::Task enables using regular blocking file descriptors
SC_TRY(fd.open("MyFile.txt", openMode));
 
// Create the async file read request and async task
AsyncFileRead asyncReadFile;
asyncReadFile.callback = [&](AsyncFileRead::Result& res)
{
    Span<char> readData;
    if(res.get(readData))
    {
        if(res.completionData.endOfFile)
        {
            // Last callback invocation done when end of file has been reached
            // - completionData.endOfFile is == true
            // - readData.sizeInBytes() is == 0
            console.print("End of file reached");
        }
        else
        {
            // readData is a slice of receivedData with the received bytes
            console.print("Read {} bytes from file", readData.sizeInBytes());
            
            // OPTIONAL: Update file offset to receive a different range of bytes
            res.getAsync().setOffset(res.getAsync().getOffset()  + readData.sizeInBytes());
            
            // IMPORTANT: Reactivate the request to receive more data
            res.reactivateRequest(true);
        }
    }
    else
    {
        // Some error occurred, check res.returnCode
    }
};
char buffer[100] = {0};
asyncReadFile.buffer = {buffer, sizeof(buffer)};
// Obtain file descriptor handle and associate it with event loop
SC_TRY(fd.get(asyncReadFile.handle, Result::Error("Invalid handle")));
 
// Start the operation on a thread pool
AsyncTaskSequence asyncFileTask;
SC_TRY(asyncReadFile.executeOn(asyncFileTask, threadPool));
SC_TRY(asyncReadFile.start(eventLoop));
 
// Alternatively if the file is opened with blocking == false, AsyncFileRead can be omitted
// but the operation will not be fully async on regular (buffered) files, except on io_uring.
//
// SC_TRY(asyncReadFile.start(eventLoop));

AsyncFileWrite

Starts a file write operation, writing bytes to a file (or pipe).

Callback will be called when the file is ready to receive more bytes to write.
Call AsyncRequest::executeOn to set a thread pool if this is a buffered file and not a pipe. This is important on APIs with blocking behaviour on buffered file I/O (all APIs except io_uring).

File library can be used to open the file and obtain a blocking or non-blocking file descriptor handle.

Note: Pipes or files opened using Posix O_DIRECT or Windows FILE_FLAG_WRITE_THROUGH & FILE_FLAG_NO_BUFFERING should instead avoid using the Task parameter for best performance.

When not using the Task remember to:

Open the file descriptor for non-blocking IO (SC::File::OpenOptions::blocking == false)
Call SC::AsyncEventLoop::associateExternallyCreatedFileDescriptor on the file descriptor

Additional notes:

io_uring backend will not use thread pool by default because that API allows proper async file read/writes
Pass AsyncThreadPoolMode::ForceThreadPool to executeOn to force using the supplied thread pool

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// ...
 
// Assuming an already created threadPool named `threadPool`
// ...
 
// Open the file (for write)
FileOpen openMode;
openMode.mode = FileOpen::Write;
openMode.blocking = true; // AsyncFileWrite::Task enables using regular blocking file descriptors
FileDescriptor fd;
SC_TRY(fd.open("MyFile.txt", openMode));
 
// Create the async file write request
AsyncFileWrite asyncWriteFile;
asyncWriteFile.callback = [&](AsyncFileWrite::Result& res)
{
    size_t writtenBytes = 0;
    if(res.get(writtenBytes))
    {
        console.print("{} bytes have been written", writtenBytes);
    }
};
// Obtain file descriptor handle
SC_TRY(fd.get(asyncWriteFile.handle, Result::Error("Invalid Handle")));
asyncWriteFile.buffer = StringView("test").toCharSpan();
// Vectorized writes: use proper start overload or set
// AsyncFileWrite::buffers and AsyncFileWrite::singleBuffer = false
    
// Start the operation in a thread pool
AsyncTaskSequence asyncFileTask;
SC_TRY(asyncWriteFile.executeOn(asyncFileTask, threadPool));
SC_TRY(asyncWriteFile.start(eventLoop));
 
// Execute another file write AFTER the previous one is finished on the same threadPool
AsyncFileWrite asyncWriteFileLater;
asyncWriteFileLater.buffer = StringView("AFTER").toCharSpan();
SC_TRY(asyncWriteFileLater.executeOn(asyncFileTask, threadPool));
SC_TRY(asyncWriteFile.start(eventLoop));
 
// Alternatively if the file is opened with blocking == false, AsyncFileRead can be omitted
// but the operation will not be fully async on regular (buffered) files, except on io_uring.
//
// SC_TRY(asyncWriteFile.start(eventLoop));

When using offsets, prefer a single contiguous buffer for portable examples and higher-level helpers. Combining scatter/gather buffers with an explicit offset needs backend-specific validation before being treated as a portable idiom.

AsyncFileReadiness

Starts a file descriptor readiness operation.

Uses kevent (macOS), epoll (Linux) and io_uring (Linux). Callback will be called when the OS signals readiness events on the given file descriptor.

AsyncExternalCompletion

Integrates externally-submitted completion based operations with AsyncEventLoop.

Manual mode is created with start(eventLoop) and completed with AsyncEventLoop::postExternalCompletion(). On Windows, native mode is created with start(eventLoop, handle) and completed by IOCP using getWindowsOverlapped().

AsyncSequence

Execute AsyncRequests serially, by submitting the next one after the previous one is completed.

Requests are being queued on a sequence using AsyncRequest::executeOn. AsyncTaskSequence can be used to force running asyncs on a thread (useful for buffered files)

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// ...
 
// Assuming an already created threadPool named `threadPool`
// ...
 
// Open the file (for write)
FileOpen openMode;
openMode.mode = FileOpen::Write;
openMode.blocking = true; // AsyncFileWrite::Task enables using regular blocking file descriptors
FileDescriptor fd;
SC_TRY(fd.open("MyFile.txt", openMode));
 
// Create the async file write request
AsyncFileWrite asyncWriteFile;
asyncWriteFile.callback = [&](AsyncFileWrite::Result& res)
{
    size_t writtenBytes = 0;
    if(res.get(writtenBytes))
    {
        console.print("{} bytes have been written", writtenBytes);
    }
};
// Obtain file descriptor handle
SC_TRY(fd.get(asyncWriteFile.handle, Result::Error("Invalid Handle")));
asyncWriteFile.buffer = StringView("test").toCharSpan();
// Vectorized writes: use proper start overload or set
// AsyncFileWrite::buffers and AsyncFileWrite::singleBuffer = false
    
// Start the operation in a thread pool
AsyncTaskSequence asyncFileTask;
SC_TRY(asyncWriteFile.executeOn(asyncFileTask, threadPool));
SC_TRY(asyncWriteFile.start(eventLoop));
 
// Execute another file write AFTER the previous one is finished on the same threadPool
AsyncFileWrite asyncWriteFileLater;
asyncWriteFileLater.buffer = StringView("AFTER").toCharSpan();
SC_TRY(asyncWriteFileLater.executeOn(asyncFileTask, threadPool));
SC_TRY(asyncWriteFile.start(eventLoop));
 
// Alternatively if the file is opened with blocking == false, AsyncFileRead can be omitted
// but the operation will not be fully async on regular (buffered) files, except on io_uring.
//
// SC_TRY(asyncWriteFile.start(eventLoop));

AsyncTaskSequence

An AsyncSequence using a SC::ThreadPool to execute one or more SC::AsyncRequest in a background thread.

Calling SC::AsyncRequest::executeOn on multiple requests with the same SC::AsyncTaskSequence queues them to be serially executed on the same thread.

AsyncFileSystemOperation

Starts an asynchronous file system operation (open, close, read, write, sendFile, stat, lstat, fstat, etc.) Some operations need a file path and others need a file descriptor.

Note: Operations will run on the thread pool set with AsyncFileSystemOperation::setThreadPool on all backends except when the event loop is using io_uring on Linux, unless AsyncThreadPoolMode::ForceThreadPool is used.

Warning: File paths must be encoded in the native encoding of the OS, that is UTF-8 on Posix and UTF-16 on Windows.

Example of async open operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Create a test file using FileSystem
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    SC_TEST_EXPECT(fs.writeString("FileSystemOperationOpen.txt", "FileSystemOperationOpen"));
 
    AsyncFileSystemOperation asyncFileSystemOperation;
    asyncFileSystemOperation.callback = [&](AsyncFileSystemOperation::Result& res)
    {
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.code == 0);
        SC_TEST_EXPECT(res.completionData.handle != FileDescriptor::Invalid);
        // Read the file content from the file descriptor handle (that is already opened)
        // and check that the content is correct. Descriptor is closed automatically by File.
        FileDescriptor fd(res.completionData.handle);
 
        String text;
        SC_TEST_EXPECT(fd.readUntilEOF(text));
        SC_TEST_EXPECT(text.view() == "FileSystemOperationOpen");
    };
    // Set the thread pool where the open operation will be run
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    // Start the open operation on the given file
    // IMPORTANT! The path string passed in must be in Native Encoding (that means UTF16 on Windows)
    String path = StringEncoding::Native;
    SC_TEST_EXPECT(Path::join(path, {report.applicationRootDirectory.view(), "FileSystemOperationOpen.txt"}));
    SC_TEST_EXPECT(asyncFileSystemOperation.open(eventLoop, path.view(), FileOpen::Read));
    SC_TEST_EXPECT(eventLoop.run());
 
    // Remove test files
    SC_TEST_EXPECT(fs.removeFile("FileSystemOperationOpen.txt"));

Example of async close operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Create a test file using FileSystem
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    SC_TEST_EXPECT(fs.writeString("FileSystemOperationClose.txt", "FileSystemOperationClose"));
 
    AsyncFileSystemOperation asyncFileSystemOperation;
 
    int callbackCalled = 0;
 
    asyncFileSystemOperation.callback = [&](AsyncFileSystemOperation::Result& res)
    {
        callbackCalled++;
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.code == 0);
    };
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    FileDescriptor fd;
    String         path = StringEncoding::Native;
    SC_TEST_EXPECT(Path::join(path, {report.applicationRootDirectory.view(), "FileSystemOperationClose.txt"}));
    SC_TEST_EXPECT(fd.open(path.view(), FileOpen::Read));
    FileDescriptor::Handle handle = FileDescriptor::Invalid;
    SC_TEST_EXPECT(fd.get(handle, Result::Error("Invalid FD")));
    fd.detach();
    SC_TEST_EXPECT(asyncFileSystemOperation.close(eventLoop, handle));
    SC_TEST_EXPECT(eventLoop.run());
    SC_TEST_EXPECT(callbackCalled == 1);
 
    // Remove test files
    SC_TEST_EXPECT(fs.removeFile("FileSystemOperationClose.txt"));

Example of async read operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Create a test file using FileSystem
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    SC_TEST_EXPECT(fs.writeString("FileSystemOperationRead.txt", "FileSystemOperationRead"));
 
    // Open the file first
    FileDescriptor fd;
    String         path = StringEncoding::Native;
    SC_TEST_EXPECT(Path::join(path, {report.applicationRootDirectory.view(), "FileSystemOperationRead.txt"}));
    SC_TEST_EXPECT(fd.open(path.view(), FileOpen::Read));
    FileDescriptor::Handle handle = FileDescriptor::Invalid;
    SC_TEST_EXPECT(fd.get(handle, Result::Error("Invalid FD")));
    fd.detach();
 
    AsyncFileSystemOperation asyncFileSystemOperation;
    asyncFileSystemOperation.callback = [&](AsyncFileSystemOperation::Result& res)
    {
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.numBytes == 23); // Length of "FileSystemOperationRead"
    };
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    // Read from the file
    char buffer[32] = {0};
    SC_TEST_EXPECT(asyncFileSystemOperation.read(eventLoop, handle, Span<char>(buffer, sizeof(buffer)), 0));
    SC_TEST_EXPECT(eventLoop.run());
    StringView readContent({buffer, 23}, true, StringEncoding::Ascii);
    SC_TEST_EXPECT(readContent == StringView("FileSystemOperationRead"));
 
    SC_TEST_EXPECT(fd.assign(handle));
    SC_TEST_EXPECT(fd.close());
 
    // Remove test files
    SC_TEST_EXPECT(fs.removeFile("FileSystemOperationRead.txt"));

Example of async write operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Open the file first
    FileDescriptor fd;
    String         path = StringEncoding::Native;
    SC_TEST_EXPECT(Path::join(path, {report.applicationRootDirectory.view(), "FileSystemOperationWrite.txt"}));
    SC_TEST_EXPECT(fd.open(path.view(), FileOpen::Write));
    FileDescriptor::Handle handle = FileDescriptor::Invalid;
    SC_TEST_EXPECT(fd.get(handle, Result::Error("Invalid FD")));
    fd.detach();
 
    AsyncFileSystemOperation asyncFileSystemOperation;
    asyncFileSystemOperation.callback = [&](AsyncFileSystemOperation::Result& res)
    {
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.numBytes == 24); // Length of "FileSystemOperationWrite"
    };
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    // Write to the file
    const char* writeData = "FileSystemOperationWrite";
    SC_TEST_EXPECT(asyncFileSystemOperation.write(eventLoop, handle, Span<const char>(writeData, 24), 0));
    SC_TEST_EXPECT(eventLoop.run());
    SC_TEST_EXPECT(fd.assign(handle));
    SC_TEST_EXPECT(fd.close());
 
    // Verify the content was written correctly
    FileDescriptor verifyFd;
    SC_TEST_EXPECT(verifyFd.open(path.view(), FileOpen::Read));
    String text;
    SC_TEST_EXPECT(verifyFd.readUntilEOF(text));
    SC_TEST_EXPECT(text.view() == "FileSystemOperationWrite");
    SC_TEST_EXPECT(verifyFd.close()); // Close before removing it
 
    // Remove test files
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    SC_TEST_EXPECT(fs.removeFile("FileSystemOperationWrite.txt"));

Example of async copy operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Create a test file using FileSystem
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    SC_TEST_EXPECT(fs.writeString("FileSystemOperationCopy.txt", "FileSystemOperationCopy"));
 
    AsyncFileSystemOperation asyncFileSystemOperation;
    asyncFileSystemOperation.callback = [&](AsyncFileSystemOperation::Result& res)
    {
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.code == 0);
    };
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    // Copy the file
    String sourcePath = StringEncoding::Native;
    String destPath   = StringEncoding::Native;
    SC_TEST_EXPECT(Path::join(sourcePath, {report.applicationRootDirectory.view(), "FileSystemOperationCopy.txt"}));
    SC_TEST_EXPECT(Path::join(destPath, {report.applicationRootDirectory.view(), "FileSystemOperationCopy2.txt"}));
    SC_TEST_EXPECT(asyncFileSystemOperation.copyFile(eventLoop, sourcePath.view(), destPath.view()));
    SC_TEST_EXPECT(eventLoop.run());
 
    // Verify the content was copied correctly
    FileDescriptor verifyFd;
    SC_TEST_EXPECT(verifyFd.open(destPath.view(), FileOpen::Read));
    String text;
    SC_TEST_EXPECT(verifyFd.readUntilEOF(text));
    SC_TEST_EXPECT(text.view() == "FileSystemOperationCopy");
    SC_TEST_EXPECT(verifyFd.close()); // Close before removing it
 
    // Remove test files
    SC_TEST_EXPECT(fs.removeFile(sourcePath.view()));
    SC_TEST_EXPECT(fs.removeFile(destPath.view()));

Example of async copy directory operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Create a test directory structure synchronously
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    SC_TEST_EXPECT(fs.makeDirectory("AsyncCopyDir"));
    SC_TEST_EXPECT(fs.writeString("AsyncCopyDir/file1.txt", "data1"));
    SC_TEST_EXPECT(fs.makeDirectory("AsyncCopyDir/subdir"));
    SC_TEST_EXPECT(fs.writeString("AsyncCopyDir/subdir/file2.txt", "data2"));
 
    // Prepare async copy operation
    AsyncFileSystemOperation asyncFileSystemOperation;
    asyncFileSystemOperation.callback = [&](AsyncFileSystemOperation::Result& res)
    {
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.code == 0);
    };
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    // Copy the directory
    String sourcePath = StringEncoding::Native;
    String destPath   = StringEncoding::Native;
    SC_TEST_EXPECT(Path::join(sourcePath, {report.applicationRootDirectory.view(), "AsyncCopyDir"}));
    SC_TEST_EXPECT(Path::join(destPath, {report.applicationRootDirectory.view(), "AsyncCopyDirCopy"}));
    SC_TEST_EXPECT(asyncFileSystemOperation.copyDirectory(eventLoop, sourcePath.view(), destPath.view()));
    SC_TEST_EXPECT(eventLoop.run());
 
    // Verify the content was copied correctly
    SC_TEST_EXPECT(fs.existsAndIsFile("AsyncCopyDirCopy/file1.txt"));
    SC_TEST_EXPECT(fs.existsAndIsFile("AsyncCopyDirCopy/subdir/file2.txt"));
    String text = StringEncoding::Ascii;
    SC_TEST_EXPECT(fs.read("AsyncCopyDirCopy/file1.txt", text));
    SC_TEST_EXPECT(text.view() == "data1");
    SC_TEST_EXPECT(fs.read("AsyncCopyDirCopy/subdir/file2.txt", text));
    SC_TEST_EXPECT(text.view() == "data2");
 
    // Cleanup
    SC_TEST_EXPECT(fs.removeFile("AsyncCopyDir/file1.txt"));
    SC_TEST_EXPECT(fs.removeFile("AsyncCopyDir/subdir/file2.txt"));
    SC_TEST_EXPECT(fs.removeEmptyDirectory("AsyncCopyDir/subdir"));
    SC_TEST_EXPECT(fs.removeEmptyDirectory("AsyncCopyDir"));
    SC_TEST_EXPECT(fs.removeFile("AsyncCopyDirCopy/file1.txt"));
    SC_TEST_EXPECT(fs.removeFile("AsyncCopyDirCopy/subdir/file2.txt"));
    SC_TEST_EXPECT(fs.removeEmptyDirectory("AsyncCopyDirCopy/subdir"));
    SC_TEST_EXPECT(fs.removeEmptyDirectory("AsyncCopyDirCopy"));

Example of async rename operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Create a test file using FileSystem
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    SC_TEST_EXPECT(fs.writeString("FileSystemOperationRename.txt", "FileSystemOperationRename"));
 
    AsyncFileSystemOperation asyncFileSystemOperation;
    asyncFileSystemOperation.callback = [&](AsyncFileSystemOperation::Result& res)
    {
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.code == 0);
    };
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    // Rename the file
    String sourcePath = StringEncoding::Native;
    String destPath   = StringEncoding::Native;
    SC_TEST_EXPECT(Path::join(sourcePath, {report.applicationRootDirectory.view(), "FileSystemOperationRename.txt"}));
    SC_TEST_EXPECT(Path::join(destPath, {report.applicationRootDirectory.view(), "FileSystemOperationRename2.txt"}));
    SC_TEST_EXPECT(asyncFileSystemOperation.rename(eventLoop, sourcePath.view(), destPath.view()));
    SC_TEST_EXPECT(eventLoop.run());
 
    // Verify the content was renamed correctly
    FileDescriptor verifyFd;
    SC_TEST_EXPECT(verifyFd.open(destPath.view(), FileOpen::Read));
    String text;
    SC_TEST_EXPECT(verifyFd.readUntilEOF(text));
    SC_TEST_EXPECT(text.view() == "FileSystemOperationRename");
    SC_TEST_EXPECT(verifyFd.close()); // Close before removing it
 
    // Remove test files
    SC_TEST_EXPECT(fs.removeFile(destPath.view()));

Example of async remove empty directory operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Create a test directory using FileSystem
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    String dirPath = StringEncoding::Native;
    SC_TEST_EXPECT(
        Path::join(dirPath, {report.applicationRootDirectory.view(), "FileSystemOperationRemoveEmptyDirectory"}));
    SC_TEST_EXPECT(fs.makeDirectory(dirPath.view()));
 
    AsyncFileSystemOperation asyncFileSystemOperation;
    int                      numCallbacks = 0;
    asyncFileSystemOperation.callback     = [&](AsyncFileSystemOperation::Result& res)
    {
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.code == 0);
        numCallbacks++;
    };
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    // Remove the empty directory
    SC_TEST_EXPECT(asyncFileSystemOperation.removeEmptyDirectory(eventLoop, dirPath.view()));
    SC_TEST_EXPECT(eventLoop.run());
    SC_TEST_EXPECT(numCallbacks == 1); // Ensure the callback was called
 
    // Verify the directory was removed
    SC_TEST_EXPECT(!fs.existsAndIsDirectory(dirPath.view()));
 

Example of async remove file operation:

    // Create Thread Pool where to run fs operations
    static constexpr int NUM_THREADS = 1;
 
    ThreadPool threadPool;
    SC_TEST_EXPECT(threadPool.create(NUM_THREADS));
 
    // Create Event Loop
    AsyncEventLoop eventLoop;
    SC_TEST_EXPECT(eventLoop.create(options));
 
    // Create a test file using FileSystem
    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    String filePath = StringEncoding::Native;
    SC_TEST_EXPECT(Path::join(filePath, {report.applicationRootDirectory.view(), "FileSystemOperationRemoveFile.txt"}));
    SC_TEST_EXPECT(fs.writeString(filePath.view(), "FileSystemOperationRemoveFile"));
 
    AsyncFileSystemOperation asyncFileSystemOperation;
    asyncFileSystemOperation.callback = [&](AsyncFileSystemOperation::Result& res)
    {
        SC_TEST_EXPECT(res.isValid());
        SC_TEST_EXPECT(res.completionData.code == 0);
    };
    SC_TEST_EXPECT(asyncFileSystemOperation.setThreadPool(threadPool));
 
    // Remove the file
    SC_TEST_EXPECT(asyncFileSystemOperation.removeFile(eventLoop, filePath.view()));
    SC_TEST_EXPECT(eventLoop.run());
 
    // Verify the file was removed
    SC_TEST_EXPECT(not fs.existsAndIsFile(filePath.view()));
 

Implementation

Library abstracts async operations by exposing a completion based mechanism. This mechanism currently maps on kqueue on macOS and OVERLAPPED on Windows.

On Linux it tries to create a direct io_uring backend first and falls back to epoll when the kernel or runtime policy does not allow it. No liburing shared library is required.

The api works on file and socket descriptors, that can be obtained from the File and Socket libraries. It also works with serial descriptors from SerialPort, by using AsyncFileRead and AsyncFileWrite on an opened SC::SerialDescriptor. Pipe endpoints accepted/connected through SC::NamedPipeServer and SC::NamedPipeClient, exposed as SC::PipeDescriptor are also supported.

On Windows, AsyncTest includes an optional real COM section named serial com0com read/write. Set SC_TEST_COM0COM_PORT_A and SC_TEST_COM0COM_PORT_B (values can be COMx or \\.\COMx) to enable it. When variables are unset, this section prints a skip message and succeeds.

Memory allocation

The entire library is free of allocations, as it uses a double linked list inside SC::AsyncRequest.
Caller is responsible for keeping AsyncRequest-derived objects memory stable until async callback is called.
SC::ArenaMap from the Containers can be used to preallocate a bounded pool of Async objects.

Roadmap

🟩 Usable Features:

More AsyncFileSystemOperations
Async DNS Resolution

🟦 Complete Features:

TTY with ANSI Escape Codes
Signal handling (multi-watcher, cross-platform)

Statistics

LOC counts exclude comments. Library counts files physically under Libraries/Async. Single File counts SaneCppAsync.h. Standalone counts SaneCppAsyncStandalone.h and intentionally includes dependency payloads.

Metric	Header	Source	Sum
Library	1926	5842	7768
Single File	1646	6974	8620
Standalone	6190	13279	19469

Table of Contents

Dependencies

Features

Details

Status

Videos

Blog

Description

AsyncEventLoop

Run modes

AsyncEventLoopMonitor

AsyncLoopTimeout

AsyncLoopWakeUp

AsyncLoopWork

AsyncProcessExit

AsyncSignal

AsyncSocketAccept

AsyncSocketConnect

AsyncSocketSend

AsyncSocketReceive

AsyncSocketSendTo

AsyncSocketReceiveFrom

AsyncFileRead

AsyncFileWrite

AsyncFileReadiness

AsyncExternalCompletion

AsyncSequence

AsyncTaskSequence

AsyncFileSystemOperation

Implementation

Memory allocation

Roadmap

Statistics