service.h

#include <google/protobuf/service.h>
namespace google::protobuf

DEPRECATED: This module declares the abstract interfaces underlying proto2 RPC services.

These are intended to be independent of any particular RPC implementation, so that proto2 services can be used on top of a variety of implementations. Starting with version 2.3.0, RPC implementations should not try to build on these, but should instead provide code generator plugins which generate code specific to the particular RPC implementation. This way the generated code can be more appropriate for the implementation in use and can avoid unnecessary layers of indirection.

When you use the protocol compiler to compile a service definition, it generates two classes: An abstract interface for the service (with methods matching the service definition) and a "stub" implementation. A stub is just a type-safe wrapper around an RpcChannel which emulates a local implementation of the service.

For example, the service definition:

service MyService {
  rpc Foo(MyRequest) returns(MyResponse);
}

will generate abstract interface "MyService" and class "MyService::Stub". You could implement a MyService as follows:

class MyServiceImpl : public MyService {
 public:
  MyServiceImpl() {}
  ~MyServiceImpl() {}

  // implements MyService ---------------------------------------

  void Foo(google::protobuf::RpcController* controller,
           const MyRequest* request,
           MyResponse* response,
           Closure* done) {
    // ... read request and fill in response ...
    done->Run();
  }
};

You would then register an instance of MyServiceImpl with your RPC server implementation. (How to do that depends on the implementation.)

To call a remote MyServiceImpl, first you need an RpcChannel connected to it. How to construct a channel depends, again, on your RPC implementation. Here we use a hypothetical "MyRpcChannel" as an example:

MyRpcChannel channel("rpc:hostname:1234/myservice");
MyRpcController controller;
MyServiceImpl::Stub stub(&channel);
FooRequest request;
FooResponse response;

// ... fill in request ...

stub.Foo(&controller, request, &response, NewCallback(HandleResponse));

On Thread-Safety:

Different RPC implementations may make different guarantees about what threads they may run callbacks on, and what threads the application is allowed to use to call the RPC system. Portable software should be ready for callbacks to be called on any thread, but should not try to call the RPC system from any thread except for the ones on which it received the callbacks. Realistically, though, simple software will probably want to use a single-threaded RPC system while high-end software will want to use multiple threads. RPC implementations should provide multiple choices.

class Service

#include <google/protobuf/service.h>
namespace google::protobuf

Abstract base interface for protocol-buffer-based RPC services.

Services themselves are abstract interfaces (implemented either by servers or as stubs), but they subclass this base interface. The methods of this interface can be used to call the methods of the Service without knowing its exact type at compile time (analogous to Reflection).

enum Service::ChannelOwnership {
  STUB_OWNS_CHANNEL,
  STUB_DOESNT_OWN_CHANNEL
}

virtual void Service::CallMethod(
        const MethodDescriptor * method,
        RpcController * controller,
        const Message * request,
        Message * response,
        Closure * done) = 0

virtual const Message & Service::GetRequestPrototype(
        const MethodDescriptor * method) const = 0

const MethodDescriptor* method =
  service->GetDescriptor()->FindMethodByName("Foo");
Message* request  = stub->GetRequestPrototype (method)->New();
Message* response = stub->GetResponsePrototype(method)->New();
request->ParseFromString(input);
service->CallMethod(method, *request, response, callback);

class RpcController

#include <google/protobuf/service.h>
namespace google::protobuf

An RpcController mediates a single method call.

The primary purpose of the controller is to provide a way to manipulate settings specific to the RPC implementation and to find out about RPC-level errors.

The methods provided by the RpcController interface are intended to be a "least common denominator" set of features which we expect all implementations to support. Specific implementations may provide more advanced features (e.g. deadline propagation).

virtual void RpcController::Reset() = 0

virtual bool RpcController::Failed() const = 0

virtual void RpcController::StartCancel() = 0

virtual void RpcController::SetFailed(
        const std::string & reason) = 0

virtual bool RpcController::IsCanceled() const = 0

virtual void RpcController::NotifyOnCancel(
        Closure * callback) = 0

class RpcChannel

#include <google/protobuf/service.h>
namespace google::protobuf

Abstract interface for an RPC channel.

An RpcChannel represents a communication line to a Service which can be used to call that Service's methods. The Service may be running on another machine. Normally, you should not call an RpcChannel directly, but instead construct a stub Service wrapping it. Example:

RpcChannel* channel = new MyRpcChannel("remotehost.example.com:1234");
MyService* service = new MyService::Stub(channel);
service->MyMethod(request, &response, callback);

virtual void RpcChannel::CallMethod(
        const MethodDescriptor * method,
        RpcController * controller,
        const Message * request,
        Message * response,
        Closure * done) = 0