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
struct	Result

Public Member Functions
uint64_t	getOffset () const
	The file/pipe descriptor handle to read data from.
void	setOffset (uint64_t fileOffset)
	Sets the offset in bytes at which start reading.
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
Span< char >	buffer
	Callback called when some data has been read from the file into the buffer.
FileDescriptor::Handle	handle
	The writeable span of memory where to data will be written.
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 read operation, reading bytes from a file (or pipe).

Callback will be called when the data read from the file (or pipe) is available.
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 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::File::OpenOptions::blocking == false)
• Call SC::AsyncEventLoop::associateExternallyCreatedFileDescriptor on the file descriptor

Additional notes:

• When reactivating the AsyncRequest, remember to increment the offset (SC::AsyncFileRead::offset)
• SC::AsyncFileRead::CompletionData::endOfFile signals end of file reached
• io_uring backend will not use thread pool because that API allows proper async file read/writes

// Assuming an already created (and running) AsyncEventLoop named `eventLoop`
// ...
 
// Assuming an already created threadPool named `eventLoop
// ...
 
// Open the file
FileDescriptor fd;
FileOpen openMode;
openMode.mode = FileOpen::Read;
openMode.blocking = true; // AsyncFileRead::Task enables using regular blocking file descriptors
SC_TRY(fd.open("MyFile.txt", openMode));
 
// Create the async file read request and async task
AsyncFileRead asyncReadFile;
asyncReadFile.callback = [&](AsyncFileRead::Result& res)
{
    Span<char> readData;
    if(res.get(readData))
    {
        if(res.completionData.endOfFile)
        {
            // Last callback invocation done when end of file has been reached
            // - completionData.endOfFile is == true
            // - readData.sizeInBytes() is == 0
            console.print("End of file reached");
        }
        else
        {
            // readData is a slice of receivedData with the received bytes
            console.print("Read {} bytes from file", readData.sizeInBytes());
            
            // OPTIONAL: Update file offset to receive a different range of bytes
            res.getAsync().setOffset(res.getAsync().getOffset()  + readData.sizeInBytes());
            
            // IMPORTANT: Reactivate the request to receive more data
            res.reactivateRequest(true);
        }
    }
    else
    {
        // Some error occurred, check res.returnCode
    }
};
char buffer[100] = {0};
asyncReadFile.buffer = {buffer, sizeof(buffer)};
// Obtain file descriptor handle and associate it with event loop
SC_TRY(fd.get(asyncReadFile.handle, Result::Error("Invalid handle")));
 
// Start the operation on a thread pool
AsyncTaskSequence asyncFileTask;
SC_TRY(asyncReadFile.executeOn(asyncFileTask, threadPool));
SC_TRY(asyncReadFile.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(asyncReadFile.start(eventLoop));

Member Function Documentation

getOffset()

uint64_t SC::AsyncFileRead::getOffset ( ) const

inline

The file/pipe descriptor handle to read data from.

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

Returns the last offset set with AsyncFileRead::setOffset

setOffset()

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

inline

Sets the offset in bytes at which start reading.

Note

Setting file offset when reading is only possible on seekable files

start()

Result SC::AsyncRequest::start

(

AsyncEventLoop &

eventLoop

)

Shortcut for AsyncEventLoop::start.

Member Data Documentation

buffer

Span<char> SC::AsyncFileRead::buffer

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

handle

FileDescriptor::Handle SC::AsyncFileRead::handle

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

---

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

• Async.h