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

#include <Async.h>

Inheritance diagram for SC::AsyncFileWrite:

Classes
struct	CompletionData

struct	Result

Public Member Functions
SC::Result	start (AsyncEventLoop &eventLoop, Span< Span< const char > > data)
	Sets async request members and calls AsyncEventLoop::start.

SC::Result	start (AsyncEventLoop &eventLoop, Span< const char > data)
	Sets async request members and calls AsyncEventLoop::start.

uint64_t	getOffset () const
	Returns the last offset set with AsyncFileWrite::setOffset.

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

Result	start (AsyncEventLoop &eventLoop)
	Shortcut for AsyncEventLoop::start.

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

void	executeOn (AsyncSequence &sequence)
	Adds the request to be executed on a specific AsyncSequence.

Result	executeOn (AsyncTaskSequence &task, ThreadPool &pool)
	Adds the request to be executed on a specific AsyncTaskSequence.

void	disableThreadPool ()
	Disables the thread-pool usage for this request.

	AsyncRequest (Type type)
	Constructs a free async request of given type.

Result	stop (AsyncEventLoop &eventLoop, Function< void(AsyncResult &)> *afterStopped=nullptr)
	Ask to stop current async operation.

bool	isFree () const
	Returns `true` if this request is free.

bool	isCancelling () const
	Returns `true` if this request is being cancelled.

bool	isActive () const
	Returns `true` if this request is active or being reactivated.

Type	getType () const
	Returns request type.

Result	start (AsyncEventLoop &eventLoop)
	Shortcut for AsyncEventLoop::start.

void	setUserFlags (uint16_t externalFlags)
	Sets user flags, holding some meaningful data for the caller.

uint16_t	getUserFlags () const
	Gets user flags, holding some meaningful data for the caller.

Function< void(AsyncResult &)> *	getCloseCallback ()
	Returns currently set close callback (if any) passed to AsyncRequest::stop.

const Function< void(AsyncResult &)> *	getCloseCallback () const

Public Attributes
Function< void(Result &)>	callback
	Callback called when descriptor is ready to be written with more data.

FileDescriptor::Handle	handle
	The file/pipe descriptor to write data to.

Span< const char >	buffer
	The read-only span of memory where to read the data from.

Span< Span< const char > >	buffers
	The read-only spans of memory where to read the data from.

bool	singleBuffer = true
	Controls if buffer or buffers will be used.

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

AsyncRequest *	prev = nullptr

Friends
struct	AsyncEventLoop

Additional Inherited Members
Public Types inherited from SC::AsyncRequest
enum class	Type : uint8_t { LoopTimeout , LoopWakeUp , LoopWork , ProcessExit , SocketAccept , SocketConnect , SocketSend , SocketSendTo , SocketReceive , SocketReceiveFrom , FileRead , FileWrite , FilePoll , FileSystemOperation }
	Type of async request. More...

Protected Member Functions inherited from SC::AsyncRequest
Result	checkState ()

void	queueSubmission (AsyncEventLoop &eventLoop)

AsyncTaskSequence *	getTask ()

Protected Attributes inherited from SC::AsyncRequest
AsyncSequence *	sequence = 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::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 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::File::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)
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));

Member Function Documentation

◆ getOffset()

uint64_t SC::AsyncFileWrite::getOffset ( ) const

inline

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/3]

Result SC::AsyncRequest::start ( AsyncEventLoop & eventLoop )

Shortcut for AsyncEventLoop::start.

◆ start() [2/3]

SC::Result SC::AsyncFileWrite::start	(	AsyncEventLoop &	eventLoop,
		Span< const char >	data )

Sets async request members and calls AsyncEventLoop::start.

◆ start() [3/3]

SC::Result SC::AsyncFileWrite::start	(	AsyncEventLoop &	eventLoop,
		Span< Span< const char > >	data )

Sets async request members and calls AsyncEventLoop::start.

Member Data Documentation

◆ buffer

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

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

◆ buffers

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

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

◆ callback

Function<void(Result&)> SC::AsyncFileWrite::callback

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

◆ handle

FileDescriptor::Handle SC::AsyncFileWrite::handle

The file/pipe descriptor to write data to.

Use SC::FileDescriptor or SC::PipeDescriptor to open it.

◆ singleBuffer

bool SC::AsyncFileWrite::singleBuffer = true

Controls if buffer or buffers will be used.

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

Async.h

Classes

Public Member Functions

Public Attributes

Friends

Additional Inherited Members