SC::AsyncFileRead Struct Reference

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

#include <Async.h>

Inheritance diagram for SC::AsyncFileRead:

Classes
struct	CompletionData
	Completion data for AsyncFileRead. More...
struct	Result
	Callback result for AsyncFileRead. More...

Public Types
using	Task = AsyncTaskOf< AsyncFileRead >
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 receive operation, that completes when data has been read from file / pipe. More...
SC::Result	start (AsyncEventLoop &eventLoop, ThreadPool &threadPool, Task &task)
	Starts a file receive operation on thread pool, that completes when data has been read from file / pipe. 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...
	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< char >	buffer
	Callback called when some data has been read from the file into the buffer. More...
uint64_t	offset = 0
	The writeable span of memory where to data will be written. More...
FileDescriptor::Handle	fileDescriptor
	Offset from file start where to start reading. Not supported on pipes. More...
Public Attributes inherited from SC::AsyncRequest
AsyncRequest *	next = nullptr
AsyncRequest *	prev = nullptr

Friends
struct	AsyncEventLoop
	The file/pipe descriptor handle to read data from. 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
AsyncEventLoop *	eventLoop = nullptr
AsyncTask *	asyncTask = nullptr

Detailed Description

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.
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 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::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 `eventLoop
// ...
 
// Open the file
FileDescriptor fd;
FileDescriptor::OpenOptions options;
options.blocking = true; // AsyncFileRead::Task enables using regular blocking file descriptors
SC_TRY(fd.open("MyFile.txt", FileDescriptor::ReadOnly, options));
 
// Create the async file read request and async task
AsyncFileRead asyncReadFile;
asyncReadFile.callback = [&](AsyncFileRead::Result& res)
{
    Span<char> readData;
    if(res.get(readData))
    {
        console.print("Read {} bytes from file", readData.sizeInBytes());
        res.reactivateRequest(true); // Ask to receive more data
    }
};
char buffer[100] = {0};
asyncReadFile.buffer = {buffer, sizeof(buffer)};
// Obtain file descriptor handle and associate it with event loop
SC_TRY(fd.get(asyncReadFile.fileDescriptor, Result::Error("Invalid handle")));
 
// Start the operation on a thread pool
AsyncFileRead::Task asyncFileTask;
SC_TRY(asyncReadFile.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(asyncReadFile.start(eventLoop));

Member Function Documentation

start() [1/2]

SC::Result SC::AsyncFileRead::start

(

AsyncEventLoop &

eventLoop

)

Starts a file receive operation, that completes when data has been read from file / pipe.

Parameters

eventLoop

The EventLoop to run this operation on

Note

SC::AsyncEventLoop::associateExternallyCreatedFileDescriptor must have been called on the AsyncFileRead::fileDescriptor

start() [2/2]

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

Starts a file receive operation on thread pool, that completes when data has been read from file / pipe.

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.

Friends And Related Function Documentation

AsyncEventLoop

friend struct AsyncEventLoop

friend

The file/pipe descriptor handle to read data from.

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

Member Data Documentation

buffer

Span<char> SC::AsyncFileRead::buffer

Callback called when some data has been read from the file into the buffer.

fileDescriptor

FileDescriptor::Handle SC::AsyncFileRead::fileDescriptor

Offset from file start where to start reading. Not supported on pipes.

offset

uint64_t SC::AsyncFileRead::offset = 0

The writeable span of memory where to data will be written.

---

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

• Async.h