asio-grpc v1.5.0
Asynchronous gRPC with Asio/unified executors
agrpc::GrpcContext Class Reference

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

#include <agrpc/grpcContext.hpp>

Inherits boost::asio::execution_context.

Public Types

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

Public Member Functions

 GrpcContext (std::unique_ptr< grpc::CompletionQueue > &&completion_queue)
 Construct a GrpcContext from a grpc::CompletionQueue More...
 
 ~GrpcContext ()
 Destruct the GrpcContext. More...
 
void run ()
 Run the grpc::CompletionQueue More...
 
void poll ()
 Poll the grpc::CompletionQueue More...
 
void stop ()
 Signal the GrpcContext to stop. More...
 
void reset () noexcept
 Bring a stopped GrpcContext back into the ready state. More...
 
bool is_stopped () const noexcept
 Is the GrpcContext in the stopped state? More...
 
executor_type get_executor () noexcept
 Get the associated executor. More...
 
executor_type get_scheduler () noexcept
 Get the associated scheduler. More...
 
allocator_type get_allocator () noexcept
 Get the associated allocator. More...
 
void work_started () noexcept
 Signal that work has started. More...
 
void work_finished () noexcept
 Signal that work has finished. More...
 
grpc::CompletionQueue * get_completion_queue () noexcept
 Get the underlying grpc::CompletionQueue More...
 
grpc::ServerCompletionQueue * get_server_completion_queue () noexcept
 Get the underlying grpc::CompletionQueue More...
 

Detailed Description

Execution context based on grpc::CompletionQueue

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

Performance recommendation: Use one GrpcContext per thread.

Constructor & Destructor Documentation

◆ GrpcContext()

agrpc::GrpcContext::GrpcContext ( std::unique_ptr< grpc::CompletionQueue > &&  completion_queue)
inlineexplicit

Construct a GrpcContext from a grpc::CompletionQueue

For servers and clients:

grpc::ServerBuilder builder;
agrpc::GrpcContext grpc_context{builder.AddCompletionQueue()};
Execution context based on grpc::CompletionQueue
Definition: grpcContext.hpp:50

For clients only:

agrpc::GrpcContext grpc_context{std::make_unique<grpc::CompletionQueue>()};

◆ ~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

◆ get_allocator()

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

Get the associated allocator.

Attention
The returned allocator may only be used for allocations within the same thread that calls run().

Thread-safe

◆ get_completion_queue()

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

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_executor()

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

Get the associated executor.

Thread-safe

◆ get_scheduler()

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

Get the associated scheduler.

Thread-safe

◆ get_server_completion_queue()

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

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

◆ is_stopped()

bool agrpc::GrpcContext::is_stopped ( ) const
inlinenoexcept

Is the GrpcContext in the stopped state?

Thread-safe

◆ poll()

void agrpc::GrpcContext::poll ( )
inline

Poll the grpc::CompletionQueue

Processes all ready completion handlers.

Attention
Only one thread may call run()/poll() at a time.

Thread-safe with regards to other functions except run(), poll() and 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.

◆ run()

void agrpc::GrpcContext::run ( )
inline

Run the 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()/poll() at a time.

Thread-safe with regards to other functions except run(), poll() and the destructor.

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

◆ work_finished()

void agrpc::GrpcContext::work_finished ( )
inlinenoexcept

Signal that work has finished.

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