class ugcs::vsm::Request_container::Request

Overview

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

#include <request_container.h>

class Request: public std::enable_shared_from_this< Request >
{
public:
    // typedefs

    typedef std::shared_ptr<Request> Ptr;
    typedef std::weak_ptr<Request> Weak_ptr;
    typedef Callback_base<void>::Ptr<> Handler;
    typedef std::unique_lock<std::mutex> Locker;

    // enums

    enum Status;

    // methods

    template <typename... Args>
    static Ptr Create(Args&&... args);

    void Set_processing_handler(const Handler& handler);
    void Set_processing_handler(Handler&& handler);
    void Set_completion_handler(const Request_container::Ptr& context, const Handler& handler);
    void Set_completion_handler(const Request_container::Ptr& context, Handler&& handler);
    void Set_cancellation_handler(const Handler& handler);
    void Set_cancellation_handler(Handler&& handler);
    void Set_done_handler(Handler& handler);
    void Set_done_handler(Handler&& handler);
    Request_container::Ptr Get_completion_context(Locker locker = Locker()) const;
    void Process(bool process_request);
    void Complete(Status status = Status::OK, Locker locker = Locker());
    void Cancel(Locker locker = Locker());
    void Abort(Locker locker = Locker());
    Locker Lock(bool acquire = true) const;
    Status Get_status() const;
    bool Is_completed() const;
    bool Is_request_processing_needed() const;
    bool Is_aborted() const;
    bool Is_processing() const;
    bool Is_completion_delivered() const;
    bool Is_completion_delivering_started() const;
    bool Is_done() const;

    bool Wait_done(
        bool process_ctx = true,
        std::chrono::milliseconds timeout = std::chrono::milliseconds::zero()
        );

    bool& Timed_out();
};

// direct descendants

class Io_request;
class Ucs_request;

Detailed Documentation

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

Typedefs

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.

typedef std::unique_lock<std::mutex> Locker

Smart lock object for request external locking.

Methods

template <typename... Args>
static Ptr Create(Args&&... args)

Create an instance.

void 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.
Invalid_op_exception	if request not in pending state.

void Set_processing_handler(Handler&& handler)

See also:

Set_processing_handler

void 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.
Invalid_op_exception	if request not in pending state.

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

See also:

Set_completion_handler

void 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.
Invalid_op_exception	if request is not in PENDING state.

void Set_cancellation_handler(Handler&& handler)

See also:

Set_cancellation_handler

void 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 Set_done_handler(Handler&& handler)

See also:

Set_done_handler.

Request_container::Ptr 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.

void 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.
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 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.
Invalid_param_exception	if invalid status value specified.
Invalid_op_exception	if request is not in allowed state (e.g. processing not yet started).

void 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 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.

Locker 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.

Status Get_status() const

Get request current status.

bool Is_completed() const

Check if request is completed.

bool Is_request_processing_needed() const

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

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

bool Is_aborted() const

Check if request is aborted.

bool Is_processing() const

Check if request is still processing.

bool Is_completion_delivered() const

Check if the request completion notification is delivered.

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.

all handlers were invoked and no more actions pending.

bool 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.

bool& Timed_out()

Access timed_out member.

This should be set/read under request lock

previous

enum ugcs::vsm::Request_container::Type

next

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