Generic request for implementing inter-threads communications and asynchronous operations. More...

#include <request_container.h>

Inheritance diagram for ugcs::vsm::Request_container::Request:

Public Types
enum	Status { Status::PENDING, Status::CANCELLATION_PENDING, Status::CANCELING, Status::PROCESSING, Status::ABORT_PENDING, Status::ABORTED, Status::RESULT_CODES, Status::OK = RESULT_CODES, Status::CANCELED }
	Request processing status which is returned by the handler or set internally. More...

typedef std::shared_ptr< Request >	Ptr
	Pointer type.

typedef std::weak_ptr< Request >	Weak_ptr
	Pointer type.

typedef Callback_base< void > ::Ptr<>	Handler
	Callback denoting a handler of the request. More...

typedef std::unique_lock < std::mutex >	Locker
	Smart lock object for request external locking. More...

Public Member Functions
void	Set_processing_handler (const Handler &handler)
	Set processing handler for the request. More...

void	Set_processing_handler (Handler &&handler)

void	Set_completion_handler (const Request_container::Ptr &context, const Handler &handler)
	Set completion handler for the request. More...

void	Set_completion_handler (const Request_container::Ptr &context, Handler &&handler)

void	Set_cancellation_handler (const Handler &handler)
	Set request cancellation handler. More...

void	Set_cancellation_handler (Handler &&handler)

void	Set_done_handler (Handler &handler)
	Set request done handler. More...

void	Set_done_handler (Handler &&handler)

Request_container::Ptr	Get_completion_context (Locker locker=Locker()) const
	Get completion context associated with the request. More...

void	Process (bool process_request)
	Process the request. More...

void	Complete (Status status=Status::OK, Locker locker=Locker())
	Complete the request processing. More...

void	Cancel (Locker locker=Locker())
	Cancel request processing. More...

void	Abort (Locker locker=Locker())
	Call this method when request is not going to be processed by Process() method but is just removed from request queue. More...

Locker	Lock (bool acquire=true) const
	Acquire lock for request internal state. More...

Status	Get_status () const
	Get request current status. More...

bool	Is_completed () const
	Check if request is completed. More...

bool	Is_request_processing_needed () const
	Return true only if the request processing (i.e. More...

bool	Is_aborted () const
	Check if request is aborted. More...

bool	Is_processing () const
	Check if request is still processing. More...

bool	Is_completion_delivered () const
	Check if the request completion notification is delivered. More...

bool	Is_completion_delivering_started () const
	Check if the request completion handler already invoked (but might not be returned yet.

bool	Is_done () const
	Check if request is fully processed, i.e. More...

bool	Wait_done (bool process_ctx=true, std::chrono::milliseconds timeout=std::chrono::milliseconds::zero())
	Wait for request is fully processed, i.e. More...

bool &	Timed_out ()
	Access timed_out member. More...

Static Public Member Functions
template<typename... Args>
static Ptr	Create (Args &&...args)
	Create an instance. More...

Protected Member Functions
virtual void	Destroy ()
	Called to destroy request. More...

bool	Is_completion_handler_present ()
	Checks the availability of the completion handler. More...

Detailed Description

Generic request for implementing inter-threads communications and asynchronous operations.

Member Typedef Documentation

typedef Callback_base<void>::Ptr<> ugcs::vsm::Request_container::Request::Handler

Callback denoting a handler of the request.

typedef std::unique_lock<std::mutex> ugcs::vsm::Request_container::Request::Locker

Smart lock object for request external locking.

Member Enumeration Documentation

enum ugcs::vsm::Request_container::Request::Status

strong

Request processing status which is returned by the handler or set internally.

Enumerator
PENDING	Request is currently pending for processing. Should never be returned from handlers.
CANCELLATION_PENDING	Request is not yet taken from processor input queue and Cancel() method was called.
CANCELING	Request was taken from processor input queue in CANCELLATION_PENDING state.
PROCESSING	Request processing handler was called and request is being processed. Should never be returned from the handler.
ABORT_PENDING	Processing was aborted by calling Abort() method and request is submitted to the completion context for a completion handler release to be made. This is necessary to safely release the completion handler which might induce side effects potentially blocking the Abort() method caller and also to make sure that possible side effects are happening in a user provided context and not in the context of Abort() method caller.
ABORTED	Processing was aborted by calling Abort() method and full cleanup is made.
RESULT_CODES	Result codes passed to Complete() method should start from this value.
OK	Request successfully processed.
CANCELED	Request was canceled.

Member Function Documentation

void ugcs::vsm::Request_container::Request::Abort ( Locker locker = Locker() )

Call this method when request is not going to be processed by Process() method but is just removed from request queue.

It also can be called when request is queued in some container so it later will be ignored when the container will try to process it. This method does nothing if request was already aborted or fully processed.

Parameters

locker Locker object which can have previously acquired lock for request internal state. It is released before the function exits.

void ugcs::vsm::Request_container::Request::Cancel ( Locker locker = Locker() )

Cancel request processing.

It does nothing if request already processed. This action behavior is defined by specific operation and processor. If unsure, it is always recommended to use Abort() instead of Cancel().

Parameters

locker Locker object which can have previously acquired lock for request internal state. It is released before the function exits.

void ugcs::vsm::Request_container::Request::Complete	(	Status	status = `Status::OK`,
		Locker	locker = `Locker()`
	)

Complete the request processing.

Request with the specified status is submitted to the associated completion context.

Parameters

status	Completion status.
locker	Locker object which can have previously acquired lock for request internal state. It is released before the function exits.

Exceptions

Invalid_param_exception	if invalid status value specified.
Invalid_op_exception	if request is not in allowed state (e.g. processing not yet started).

template<typename... Args>

static Ptr ugcs::vsm::Request_container::Request::Create ( Args &&... args )

inlinestatic

Create an instance.

Examples:: async_workflow.cpp.

virtual void ugcs::vsm::Request_container::Request::Destroy ( )

protectedvirtual

Called to destroy request.

Primarily should be used by derived classes to destroy circular references if such exist.

Request_container::Ptr ugcs::vsm::Request_container::Request::Get_completion_context ( Locker locker = Locker() ) const

Get completion context associated with the request.

It might be null if request is already fully processed or not yet fully prepared.

Status ugcs::vsm::Request_container::Request::Get_status ( ) const

inline

Get request current status.

bool ugcs::vsm::Request_container::Request::Is_aborted ( ) const

inline

Check if request is aborted.

bool ugcs::vsm::Request_container::Request::Is_completed ( ) const

inline

Check if request is completed.

bool ugcs::vsm::Request_container::Request::Is_completion_delivered ( ) const

inline

Check if the request completion notification is delivered.

bool ugcs::vsm::Request_container::Request::Is_completion_handler_present ( )

protected

Checks the availability of the completion handler.

Request should be locked by the caller. XXX This is a workaround for the Io_request bad design related to references to the result and buffer arguments.

bool ugcs::vsm::Request_container::Request::Is_done ( ) const

inline

Check if request is fully processed, i.e.

all handlers were invoked and no more actions pending.

bool ugcs::vsm::Request_container::Request::Is_processing ( ) const

inline

Check if request is still processing.

bool ugcs::vsm::Request_container::Request::Is_request_processing_needed ( ) const

inline

Return true only if the request processing (i.e.

Process(true)) is needed for this request, otherwise false.

Locker ugcs::vsm::Request_container::Request::Lock ( bool acquire = true ) const

Acquire lock for request internal state.

It is safe to assume that request state will not be changed while the lock is acquired (e.g. aborted). Use std::move to pass the returned object to Complete() or Abort() method if you atomic request completion or aborting.

Parameters

acquire Should the lock be acqired or not.

Returns: Lock object.

void ugcs::vsm::Request_container::Request::Process ( bool process_request )

Process the request.

Either processing or completion context is called depending on request state.

Parameters

process_request true if request processing is intended or false if completion notification processing is intended.

Exceptions

Invalid_op_exception	if the method is called more than once for processing and notification handling, or calling sequence is invalid.
Nullptr_exception	if corresponding handler is not set.

void ugcs::vsm::Request_container::Request::Set_cancellation_handler ( const Handler & handler )

Set request cancellation handler.

It is fired when Abort() method is called between request processing started and Complete() is called (i.e. while request is in PROCESSING state). The second case is calling request Cancel() method when request is either in input queue or being processed. Correct handling in the handler is taking lock on the request and checking its state (either PROCESSING or ABORTED). In PROCESSING state it is legal to call Complete() method (either instantly or by deferred invocation), or do nothing if cancellation is not supported or cannot be done in current state. In ABORTED state all platform resources should be released, no further submits for the request will be done.

Parameters

handler Cancellation handler.

Exceptions

Invalid_op_exception if request is not in PENDING state.

void ugcs::vsm::Request_container::Request::Set_cancellation_handler ( Handler && handler )

See Also: Set_cancellation_handler

void ugcs::vsm::Request_container::Request::Set_completion_handler	(	const Request_container::Ptr &	context,
		const Handler &	handler
	)

Set completion handler for the request.

It is called when request is completed in the specified completion context.

Parameters

context	Context where completion handler should be invoked.
handler	Completion handler to call when request is processed.

Exceptions

Invalid_op_exception if request not in pending state.

void ugcs::vsm::Request_container::Request::Set_completion_handler	(	const Request_container::Ptr &	context,
		Handler &&	handler
	)

See Also: Set_completion_handler

void ugcs::vsm::Request_container::Request::Set_done_handler ( Handler & handler )

Set request done handler.

The handler is invoked when request is advanced to done state - no more actions are pending for it and it is destroyed. The handler is always called - in both normal completion or abortion scenario. If request is already done when this function is called, the handler is invoked immediately. Calling context is either completion, abortion or this method calling context.

void ugcs::vsm::Request_container::Request::Set_done_handler ( Handler && handler )

See Also: Set_done_handler.

void ugcs::vsm::Request_container::Request::Set_processing_handler ( const Handler & handler )

Set processing handler for the request.

It is called when request is about to be processed in the target processor context.

Parameters

handler Processing handler to invoke.

Exceptions

Invalid_op_exception if request not in pending state.

void ugcs::vsm::Request_container::Request::Set_processing_handler ( Handler && handler )

See Also: Set_processing_handler

bool& ugcs::vsm::Request_container::Request::Timed_out ( )

inline

Access timed_out member.

This should be set/read under request lock

bool ugcs::vsm::Request_container::Request::Wait_done	(	bool	process_ctx = `true`,
		std::chrono::milliseconds	timeout = `std::chrono::milliseconds::zero()`
	)

Wait for request is fully processed, i.e.

all handlers were invoked and no more actions pending.

Parameters

process_ctx	Process all requests in the associated completion context. This may be useful if the context is normally processed in the calling thread.
timeout	Timeout value for waiting. Zero value indicates indefinite waiting.

Returns: "true" if request was processed, "false" if the function returned by timeout expiration.

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

request_container.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation