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

#include <Async.h>

Inheritance diagram for SC::AsyncFileWrite:

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...

uint64_t	getOffset () const
	The file/pipe descriptor to write data to. More...

void	setOffset (uint64_t fileOffset)
	Sets the offset in bytes at which start writing. More...

Public Member Functions inherited from SC::AsyncRequest
void	setDebugName (const char *newDebugName)

AsyncEventLoop *	getEventLoop () const
	Get the event loop associated with this AsyncRequest. More...

void	cacheInternalEventLoop (AsyncEventLoop &loop)
	Caches 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...

bool	isFree () const

Public Attributes
Function< void(Result &)>	callback

Span< const char >	buffer
	Callback called when descriptor is ready to be written with more data. More...

FileDescriptor::Handle	fileDescriptor
	The read-only span of memory where to read the data from. More...

Public Attributes inherited from SC::AsyncRequest
AsyncRequest *	next = nullptr

AsyncRequest *	prev = nullptr

Friends
struct	AsyncEventLoop

Additional Inherited Members
Protected Member Functions inherited from SC::AsyncRequest
Result	validateAsync ()

Result	queueSubmission (AsyncEventLoop &eventLoop)

Result	queueSubmission (AsyncEventLoop &eventLoop, ThreadPool &threadPool, AsyncTask &task)

Protected Attributes inherited from SC::AsyncRequest
AsyncEventLoop *	eventLoop = nullptr

AsyncTask *	asyncTask = 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:

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

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

Member Function Documentation

◆ getOffset()

uint64_t SC::AsyncFileWrite::getOffset ( ) const

inline

The file/pipe descriptor to write data to.

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

Returns the last offset set with AsyncFileWrite::setOffset

◆ setOffset()

void SC::AsyncFileWrite::setOffset ( uint64_t fileOffset )

inline

Sets the offset in bytes at which start writing.

Note: Setting write file offset when reading is only possible on seekable files

◆ 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

eventLoop The 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

eventLoop	The EventLoop to run this operation on
threadPool	The ThreadPool where to run this background operation
task	The 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.

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

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

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

Async.h

Classes

Public Types

Public Member Functions

Public Attributes

Friends

Additional Inherited Members