SC::AsyncRequest Struct Reference

Base class for all async requests, holding state and type. More...

#include <Async.h>

Inheritance diagram for SC::AsyncRequest:

Public Types
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
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
AsyncRequest *	next = nullptr
AsyncRequest *	prev = nullptr

Protected Member Functions
Result	validateAsync ()
void	queueSubmission (AsyncEventLoop &eventLoop)

Protected Attributes
AsyncEventLoop *	eventLoop = nullptr
AsyncTask *	asyncTask = nullptr

Friends
struct	AsyncEventLoop

Detailed Description

Base class for all async requests, holding state and type.

An async operation is struct derived from AsyncRequest asking for some I/O to be done made to the OS.
Every async operation has an associated callback that is invoked when the request is fulfilled. If the start function returns a valid (non error) Return code, then the user callback will be called both in case of success and in case of any error.
If the function returns an invalid Return code or if the operation is manually cancelled with SC::AsyncRequest::stop, then the user callback will not be called.

Note

The memory address of all AsyncRequest derived objects must be stable until user callback is executed.

• If request is not re-activated (i.e. result.reactivateRequest(true) is NOT called) then the async request can be freed as soon as the user callback is called (even inside the callback itself).
• If request is re-activated (i.e. result.reactivateRequest(true) is called) then the async cannot be freed as it's still in use.

Some implementation details: SC::AsyncRequest::state dictates the lifetime of the async request according to a state machine.

Regular Lifetime of an Async request (called just async in the paragraph below):

1. An async that has been started, will be pushed in the submission queue with state == State::Setup.
2. Inside stageSubmission a started async will be do the one time setup (with setupAsync)
3. Inside stageSubmission a Setup or Submitting async will be activated (with activateAsync)
4. If activateAsync is successful, the async becomes state == State::Active.
   • When this happens, the async is either tracked by the kernel or in one of the linked lists like activeLoopWakeUps
5. The Active async can become completed, when the kernel signals its completion (or readiness...):
   • [default] -> Async is complete and it will be teardown and freed (state == State::Free)
   • result.reactivateRequest(true) -> Async gets submitted again (state == State::Submitting) (3.)

Cancellation of an async: An async can be cancelled at any time:

1. Async not yet submitted in State::Setup --> it just gets removed from the submission queue
2. Async in submission queue but already setup --> it will receive a teardownAsync
3. Async in Active state (so after setupAsync and activateAsync) --> will receive cancelAsync and teardownAsync

Any other case is considered an error (trying to cancel an async already being cancelled or being teardown).

Member Enumeration Documentation

Type

enum class SC::AsyncRequest::Type : uint8_t

strong

Type of async request.

Enumerator
LoopTimeout	Request is an AsyncLoopTimeout object.
LoopWakeUp	Request is an AsyncLoopWakeUp object.
LoopWork	Request is an AsyncLoopWork object.
ProcessExit	Request is an AsyncProcessExit object.
SocketAccept	Request is an AsyncSocketAccept object.
SocketConnect	Request is an AsyncSocketConnect object.
SocketSend	Request is an AsyncSocketSend object.
SocketReceive	Request is an AsyncSocketReceive object.
SocketClose	Request is an AsyncSocketClose object.
FileRead	Request is an AsyncFileRead object.
FileWrite	Request is an AsyncFileWrite object.
FileClose	Request is an AsyncFileClose object.
FilePoll	Request is an AsyncFilePoll object.

Constructor & Destructor Documentation

AsyncRequest()

SC::AsyncRequest::AsyncRequest ( Type  type )

inline

Constructs a free async request of given type.

Parameters

type	Type of this specific request

Member Function Documentation

cacheInternalEventLoop()

void SC::AsyncRequest::cacheInternalEventLoop ( AsyncEventLoop &  loop )

inline

Caches the event loop associated with this AsyncRequest.

Used to cache eventLoop pointer before starting the AsyncRequest.

getEventLoop()

AsyncEventLoop * SC::AsyncRequest::getEventLoop ( ) const

inline

Get the event loop associated with this AsyncRequest.

resetThreadPoolAndTask()

void SC::AsyncRequest::resetThreadPoolAndTask

(

)

Resets anything previously set with setThreadPoolAndTask.

setThreadPoolAndTask()

Result SC::AsyncRequest::setThreadPoolAndTask	(	ThreadPool &	pool,
		AsyncTask &	task
	)

Sets the thread pool and task to use for this request.

See also

AsyncFileRead

AsyncFileWrite

stop()

Result SC::AsyncRequest::stop

(

)

Stops the async operation.

Ask to stop current async operation

Returns

true if the stop request has been successfully queued

---

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

• Async.h