VSM C++ SDK
Vehicle Specific Modules SDK
ugcs::vsm::Request_container::Request Class Reference

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

#include <request_container.h>

Inheritance diagram for ugcs::vsm::Request_container::Request:
ugcs::vsm::Io_request ugcs::vsm::Ucs_request ugcs::vsm::Read_request ugcs::vsm::Write_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< RequestPtr
 Pointer type.
 
typedef std::weak_ptr< RequestWeak_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

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

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
lockerLocker 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
lockerLocker 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
statusCompletion status.
lockerLocker object which can have previously acquired lock for request internal state. It is released before the function exits.
Exceptions
Invalid_param_exceptionif invalid status value specified.
Invalid_op_exceptionif 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
acquireShould 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_requesttrue if request processing is intended or false if completion notification processing is intended.
Exceptions
Invalid_op_exceptionif the method is called more than once for processing and notification handling, or calling sequence is invalid.
Nullptr_exceptionif 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
handlerCancellation handler.
Exceptions
Invalid_op_exceptionif request is not in PENDING state.
void ugcs::vsm::Request_container::Request::Set_cancellation_handler ( Handler &&  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
contextContext where completion handler should be invoked.
handlerCompletion handler to call when request is processed.
Exceptions
Invalid_op_exceptionif request not in pending state.
void ugcs::vsm::Request_container::Request::Set_completion_handler ( const Request_container::Ptr context,
Handler &&  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
handlerProcessing handler to invoke.
Exceptions
Invalid_op_exceptionif request not in pending state.
void ugcs::vsm::Request_container::Request::Set_processing_handler ( Handler &&  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_ctxProcess all requests in the associated completion context. This may be useful if the context is normally processed in the calling thread.
timeoutTimeout 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: