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:

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...
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...
Result	setThreadPoolAndTask (ThreadPool &pool, AsyncTask &task)
	Sets the thread pool and task to use for this request. More...
void	resetThreadPoolAndTask ()
	Resets anything previously set with setThreadPoolAndTask. 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 ()
void	queueSubmission (AsyncEventLoop &eventLoop)
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.
Call AsyncRequest::setThreadPoolAndTask 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 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.setThreadPoolAndTask(threadPool, asyncFileTask));
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));

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.

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

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

• Use AsyncRequest::setThreadPoolAndTask to set a thread pool and task prior to start.
• Only files opened for direct IO (O_DIRECT / FILE_FLAG_WRITE_THROUGH & FILE_FLAG_NO_BUFFERING) can be used in non-blocking mode (OpenOptions::blocking == false) without a thread pool and SC::AsyncEventLoop::associateExternallyCreatedFileDescriptor must have been called on the passed in handle.
• io_uring backend will not use thread pool 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