Sane C++ Libraries
C++ Platform Abstraction Libraries
SC::AsyncFileWrite Struct Reference

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

#include <Async.h>

Inheritance diagram for SC::AsyncFileWrite:
SC::AsyncRequest

Classes

struct  CompletionData
 Completion data for AsyncFileWrite. More...
 
struct  Result
 Callback result for AsyncFileWrite. More...
 

Public Types

using Task = AsyncTaskOf< AsyncFileWrite >
 
- Public Types inherited from SC::AsyncRequest
enum class  Type : uint8_t {
  LoopTimeout ,
  LoopWakeUp ,
  LoopWork ,
  ProcessExit ,
  SocketAccept ,
  SocketConnect ,
  SocketSend ,
  SocketReceive ,
  SocketClose ,
  FileRead ,
  FileWrite ,
  FileClose ,
  FilePoll
}
 Type of async request. More...
 

Public Member Functions

SC::Result start (AsyncEventLoop &eventLoop)
 Starts a file write operation that completes when it's ready to receive more bytes. More...
 
SC::Result start (AsyncEventLoop &eventLoop, ThreadPool &threadPool, Task &task)
 Starts a file write operation on thread pool that completes when it's ready to receive more bytes. More...
 
- Public Member Functions inherited from SC::AsyncRequest
void setDebugName (const char *newDebugName)
 
AsyncEventLoopgetEventLoop () const
 Get the event loop associated with this AsyncRequest. More...
 
 AsyncRequest (Type type)
 Constructs a free async request of given type. More...
 
Result stop ()
 Stops the async operation. More...
 

Public Attributes

Function< void(Result &)> callback
 
Span< const char > buffer
 Callback called when descriptor is ready to be written with more data. More...
 
uint64_t offset = 0
 The read-only span of memory where to read the data from. More...
 
FileDescriptor::Handle fileDescriptor
 Offset to start writing from. Not supported on pipes. More...
 
- Public Attributes inherited from SC::AsyncRequest
AsyncRequestnext = nullptr
 
AsyncRequestprev = nullptr
 

Friends

struct AsyncEventLoop
 The file/pipe descriptor to write data to. More...
 

Additional Inherited Members

- Protected Member Functions inherited from SC::AsyncRequest
Result validateAsync ()
 
Result queueSubmission (AsyncEventLoop &eventLoop)
 
Result queueSubmission (AsyncEventLoop &eventLoop, ThreadPool &threadPool, AsyncTask &task)
 
- Static Protected Member Functions inherited from SC::AsyncRequest
static void updateTime (AsyncEventLoop &loop)
 
- Protected Attributes inherited from SC::AsyncRequest
AsyncEventLoopeventLoop = nullptr
 
AsyncTaskasyncTask = nullptr
 

Detailed Description

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.
Use the start overload with ThreadPool / Task parameters to execute file read on a background thread. This is important on APIs with blocking behaviour on buffered file I/O (all apis with the exception of 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:

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// ...
// Assuming an already created threadPool named `threadPool`
// ...
// Open the file (for write)
FileDescriptor::OpenOptions options;
options.blocking = true; // AsyncFileWrite::Task enables using regular blocking file descriptors
FileDescriptor fd;
SC_TRY(fd.open("MyFile.txt", FileDescriptor::WriteCreateTruncate, options));
// 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.fileDescriptor, Result::Error("Invalid Handle")));
asyncWriteFile.buffer = StringView("test").toCharSpan();;
// Start the operation in a thread pool
AsyncFileWrite::Task asyncFileTask;
SC_TRY(asyncWriteFile.start(eventLoop, threadPool, asyncFileTask));
// 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));
#define SC_TRY(expression)
Checks the value of the given expression and if failed, returns this value to caller.
Definition: Result.h:47
@ WriteCreateTruncate
Opens in write mode, creating or truncating it if another file exists at same location.
Definition: FileDescriptor.h:63
static constexpr Result Error(const char(&msg)[numChars])
Constructs an Error from a pointer to an ASCII string literal.
Definition: Result.h:23

Member Function Documentation

◆ start() [1/2]

SC::Result SC::AsyncFileWrite::start ( AsyncEventLoop eventLoop)

Starts a file write operation that completes when it's ready to receive more bytes.

Parameters
eventLoopThe EventLoop to run this operation on
Note
SC::AsyncEventLoop::associateExternallyCreatedFileDescriptor must have been called on the AsyncFileWrite::fileDescriptor

◆ start() [2/2]

SC::Result SC::AsyncFileWrite::start ( AsyncEventLoop eventLoop,
ThreadPool threadPool,
Task task 
)

Starts a file write operation on thread pool that completes when it's ready to receive more bytes.

Parameters
eventLoopThe EventLoop to run this operation on
threadPoolThe ThreadPool where to run this background operation
taskThe task used to run the operation on background thread. It's useful for any file not opened for direct IO (O_DIRECT / FILE_FLAG_WRITE_THROUGH & FILE_FLAG_NO_BUFFERING).
Note
Task will not be used on the io_uring backend, because that API allows proper async file read/writes.

Friends And Related Function Documentation

◆ AsyncEventLoop

friend struct AsyncEventLoop
friend

The file/pipe descriptor to write data to.

Use SC::FileDescriptor or SC::PipeDescriptor to open it, with SC::FileDescriptorOpenOptions::blocking == false

Member Data Documentation

◆ buffer

Span<const char> SC::AsyncFileWrite::buffer

Callback called when descriptor is ready to be written with more data.

◆ fileDescriptor

FileDescriptor::Handle SC::AsyncFileWrite::fileDescriptor

Offset to start writing from. Not supported on pipes.

◆ offset

uint64_t SC::AsyncFileWrite::offset = 0

The read-only span of memory where to read the data from.


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