agrpc::GrpcContext Class Reference

Execution context based on grpc::CompletionQueue More...

#include <agrpc/grpc_context.hpp>

Public Types
using	executor_type = agrpc::BasicGrpcExecutor<>
	The associated executor type.
using	allocator_type = detail::GrpcContextLocalAllocator
	The associated allocator type.

Public Member Functions
	GrpcContext ()
	Construct a GrpcContext for gRPC clients.
	GrpcContext (std::size_t concurrency_hint)
	Construct a GrpcContext for multi-threaded gRPC clients.
	GrpcContext (std::unique_ptr< grpc::ServerCompletionQueue > completion_queue)
	Construct a GrpcContext for gRPC servers.
	GrpcContext (std::unique_ptr< grpc::ServerCompletionQueue > completion_queue, std::size_t concurrency_hint)
	Construct a GrpcContext for multi-threaded gRPC servers.
	~GrpcContext ()
	Destruct the GrpcContext.
bool	run ()
	Run ready completion handlers and grpc::CompletionQueue
template<class Deadline >
bool	run_until (const Deadline &deadline)
	Run ready completion handlers and grpc::CompletionQueue until deadline.
template<class Condition >
bool	run_while (Condition &&condition)
	Run ready completion handlers and grpc::CompletionQueue while a condition holds.
bool	run_completion_queue ()
	Run the grpc::CompletionQueue
bool	poll ()
	Poll ready completion handlers and grpc::CompletionQueue
bool	poll_completion_queue ()
	Poll the grpc::CompletionQueue
void	stop ()
	Signal the GrpcContext to stop.
void	reset () noexcept
	Bring a stopped GrpcContext back into the ready state.
bool	is_stopped () const noexcept
	Is the GrpcContext in the stopped state?
executor_type	get_executor () noexcept
	Get the associated executor.
executor_type	get_scheduler () noexcept
	Get the associated scheduler.
allocator_type	get_allocator () noexcept
	Get the associated allocator.
void	work_started () noexcept
	Signal that work has started.
void	work_finished () noexcept
	Signal that work has finished.
grpc::CompletionQueue *	get_completion_queue () noexcept
	Get the underlying grpc::CompletionQueue
grpc::ServerCompletionQueue *	get_server_completion_queue () noexcept
	Get the underlying grpc::CompletionQueue

Detailed Description

Execution context based on grpc::CompletionQueue

Satisfies the ExecutionContext requirements and can therefore be used in all places where Asio expects an ExecutionContext.

Performance recommendation: Use exactly one GrpcContext per thread.

Constructor & Destructor Documentation

GrpcContext() [1/4]

agrpc::GrpcContext::GrpcContext ( )

inline

Construct a GrpcContext for gRPC clients.

Since

2.4.0

GrpcContext() [2/4]

agrpc::GrpcContext::GrpcContext ( std::size_t concurrency_hint )

inlineexplicit

Construct a GrpcContext for multi-threaded gRPC clients.

• concurrency_hint If greater than one then this GrpcContext's run*()/poll*() functions may be called from multiple threads

Since

3.2.0

GrpcContext() [3/4]

agrpc::GrpcContext::GrpcContext ( std::unique_ptr< grpc::ServerCompletionQueue > completion_queue )

inlineexplicit

Construct a GrpcContext for gRPC servers.

The resulting GrpcContext can also be used for clients.

Example:

    grpc::ServerBuilder builder;
    agrpc::GrpcContext grpc_context{builder.AddCompletionQueue()};

GrpcContext() [4/4]

agrpc::GrpcContext::GrpcContext ( std::unique_ptr< grpc::ServerCompletionQueue > completion_queue, std::size_t concurrency_hint )

inline

Construct a GrpcContext for multi-threaded gRPC servers.

The resulting GrpcContext can also be used for clients.

Example:

    const auto concurrency = std::thread::hardware_concurrency();
    grpc::ServerBuilder builder;
    agrpc::GrpcContext grpc_context{builder.AddCompletionQueue(), concurrency};
    // ... register services, start server
    std::vector<std::thread> threads(concurrency);
    for (auto& thread : threads)
    {
        thread = std::thread{[&]
                             {
                                 // ... register rpc handlers
                                 grpc_context.run();
                             }};
    }
    for (auto& thread : threads)
    {
        thread.join();
    }

• concurrency_hint If greater than one then this GrpcContext's run*()/poll*() functions may be called from multiple threads

Since

3.2.0

~GrpcContext()

agrpc::GrpcContext::~GrpcContext ( )

inline

Destruct the GrpcContext.

Calls Shutdown() on the grpc::CompletionQueue and drains it. Pending completion handlers will not be invoked.

Attention

Make sure to destruct the GrpcContext before destructing the grpc::Server.

Member Function Documentation

run()

bool agrpc::GrpcContext::run ( )

inline

Run ready completion handlers and grpc::CompletionQueue

Runs the main event loop logic until the GrpcContext runs out of work or is stopped. The GrpcContext will be brought into the ready state when this function is invoked. Upon return, the GrpcContext will be in the stopped state.

Attention

Only one thread may call run(), run_until(), run_while() or poll() at a time [unless this context has been constructed with a concurrency_hint greater than one. Even then it may not be called concurrently with run_completion_queue() or poll_completion_queue() (since 3.2.0)].

Returns

True if at least one operation has been processed.

run_until()

template<class Deadline >

bool agrpc::GrpcContext::run_until ( const Deadline & deadline )

inline

Run ready completion handlers and grpc::CompletionQueue until deadline.

Runs the main event loop logic until the GrpcContext runs out of work, is stopped or the specified deadline has been reached. The GrpcContext will be brought into the ready state when this function is invoked.

Attention

Only one thread may call run(), run_until(), run_while() or poll() at a time [unless this context has been constructed with a concurrency_hint greater than one. Even then it may not be called concurrently with run_completion_queue() or poll_completion_queue() (since 3.2.0)].

Template Parameters

Deadline

A type that is compatible with grpc::TimePoint<Deadline>.

Returns

True if at least one operation has been processed.

Since

2.0.0

run_while()

template<class Condition >

bool agrpc::GrpcContext::run_while ( Condition && condition )

inline

Run ready completion handlers and grpc::CompletionQueue while a condition holds.

Runs the main event loop logic until the GrpcContext runs out of work, is stopped or the specified condition returns false. The GrpcContext will be brought into the ready state when this function is invoked.

Attention

Only one thread may call run(), run_until(), run_while() or poll() at a time [unless this context has been constructed with a concurrency_hint greater than one. Even then it may not be called concurrently with run_completion_queue() or poll_completion_queue() (since 3.2.0)].

Template Parameters

Condition

A callable that returns false when the GrpcContext should stop.

Returns

True if at least one operation has been processed.

Since

2.2.0

run_completion_queue()

bool agrpc::GrpcContext::run_completion_queue ( )

inline

Run the grpc::CompletionQueue

Runs the main event loop logic until the GrpcContext runs out of work or is stopped. Only events from the grpc::CompletionQueue will be handled. That means that completion handler that were e.g. created using asio::post(grpc_context, ...) will not be processed. The GrpcContext will be brought into the ready state when this function is invoked. Upon return, the GrpcContext will be in the stopped state.

Attention

Only one thread may call run_completion_queue() or poll_completion_queue() at a time [unless this context has been constructed with a concurrency_hint greater than one. Even then it may not be called concurrently with run, run_until, run_while and poll (since 3.2.0)].

Returns

True if at least one event has been processed.

poll()

bool agrpc::GrpcContext::poll ( )

inline

Poll ready completion handlers and grpc::CompletionQueue

Processes all ready completion handlers and ready events of the grpc::CompletionQueue. The GrpcContext will be brought into the ready state when this function is invoked.

Attention

Only one thread may call run(), run_until(), run_while() or poll() at a time [unless this context has been constructed with a concurrency_hint greater than one. Even then it may not be called concurrently with run_completion_queue() or poll_completion_queue() (since 3.2.0)].

Returns

True if at least one operation has been processed.

poll_completion_queue()

bool agrpc::GrpcContext::poll_completion_queue ( )

inline

Poll the grpc::CompletionQueue

Processes only ready events of the grpc::CompletionQueue. That means that completion handler that were e.g. created using asio::post(grpc_context, ...) will not be processed. The GrpcContext will be brought into the ready state when this function is invoked.

Attention

Only one thread may call run_completion_queue() or poll_completion_queue() at a time [unless this context has been constructed with a concurrency_hint greater than one. Even then it may not be called concurrently with run, run_until, run_while and poll (since 3.2.0)].

Returns

True if at least one operation has been processed.

stop()

void agrpc::GrpcContext::stop ( )

inline

Signal the GrpcContext to stop.

Causes a call to run() to return as soon as possible.

Thread-safe with regards to other functions except the destructor.

reset()

void agrpc::GrpcContext::reset ( )

inlinenoexcept

Bring a stopped GrpcContext back into the ready state.

When a call to run() or stop() returns, the GrpcContext will be in a stopped state. This function brings the GrpcContext back into the ready state.

Thread-safe with regards to other functions except the destructor.

is_stopped()

bool agrpc::GrpcContext::is_stopped ( ) const

inlinenodiscardnoexcept

Is the GrpcContext in the stopped state?

Thread-safe

get_executor()

GrpcContext::executor_type agrpc::GrpcContext::get_executor ( )

inlinenodiscardnoexcept

Get the associated executor.

Thread-safe

get_scheduler()

GrpcContext::executor_type agrpc::GrpcContext::get_scheduler ( )

inlinenodiscardnoexcept

Get the associated scheduler.

Thread-safe

get_allocator()

GrpcContext::allocator_type agrpc::GrpcContext::get_allocator ( )

inlinenodiscardnoexcept

Get the associated allocator.

Attention

The returned allocator may only be used for allocations/deallocations within the same thread(s) that calls run*()/poll*().

Thread-safe

work_started()

void agrpc::GrpcContext::work_started ( )

inlinenoexcept

Signal that work has started.

The GrpcContext maintains an internal counter on how many operations have been started. Once that counter reaches zero it will go into the stopped state. Every call to work_started() should be matched to a call of work_finished().

Thread-safe

work_finished()

void agrpc::GrpcContext::work_finished ( )

inlinenoexcept

Signal that work has finished.

Thread-safe

get_completion_queue()

grpc::CompletionQueue * agrpc::GrpcContext::get_completion_queue ( )

inlinenodiscardnoexcept

Get the underlying grpc::CompletionQueue

Do not use any functions of the returned CompletionQueue that might interfere with the GrpcContext, like Next().

Do not delete the returned pointer.

Thread-safe, never nullptr

get_server_completion_queue()

grpc::ServerCompletionQueue * agrpc::GrpcContext::get_server_completion_queue ( )

inlinenodiscardnoexcept

Get the underlying grpc::CompletionQueue

Do not use any functions of the returned CompletionQueue that might interfere with the GrpcContext, like Next().

Do not delete the returned pointer.

Attention

Only valid if the GrpcContext has been constructed with a ServerCompletionQueue:

    grpc::ServerBuilder builder;
    agrpc::GrpcContext grpc_context{builder.AddCompletionQueue()};

Thread-safe, never nullptr