Macro dispatch_service_async 

macro_rules! dispatch_service_async {
    (
        $service:ty,
        $hash_by:ident : $hash_type:ty,

        [ $(
            $shard_mutable_method:ident ($shard_mutable_request:ty) -> $shard_mutable_reply:ty,
        )* ],

        [ $(
            $shard_readonly_method:ident ($shard_readonly_request:ty) -> $shard_readonly_reply:ty,
        )* ],

        [ $(
            $item_mutable_method:ident ($item_mutable_request:ty) -> $item_mutable_reply:ty,
        )* ],

        [ $(
            $item_readonly_method:ident ($item_readonly_request:ty) -> $item_readonly_reply:ty,
        )* ]
    ) => { ... };
}

Define the service and build the mapping relationship between tonic network tasks and your asynchronous business tasks.

Use dispatch_service_sync! instead for synchronous mode. See the module-level documentation for more information about the 2 modes.

Parameters:

• $service Original service name. Because we need to generate new service name based on this name, so do not give the module prefix.

• $hash_by: $hash_type The field in request types which is used to calculate which business task to dispatched to. All request types should contain this field.

• $shard_mutable_method ($shard_mutable_request) -> $shard_mutable_reply gRPC methods that work on mutable shard (but not on item). E.g. create or remove items on the shard.

• $shard_readonly_method ($shard_readonly_request) -> $shard_readonly_reply gRPC methods that work on readonly shard (but not on item). E.g. list items on the shard.

• $item_mutable_method ($item_mutable_request) -> $item_mutable_reply gRPC mutable methods that work on item. E.g. update item itself.

• $item_readonly_method ($item_readonly_request) -> $item_readonly_reply gRPC readonly methods that work on item. E.g. query item itself.

This macro defines 4 items:

• trait DispatchBackendShard is for each backend shard. You need to implement this trait for your shard context. It has 2 parts:

  1. associated type Item, and get_item/get_item_mut methods;
  2. gRPC methods that works at shard (but not item), e.g. create/delete.

• trait DispatchBackendItem is for each backend item. It has mutable and readonly gRPC methods that works at item. You need to implement this trait for your item.

  The formats of all methods are similar to the original tonic ones, except that changes

  • self: from &self to &mut self (for mutable methods)
  • parameter: from Request<R> to R
  • retuen value: from Response<R> to R

  However the meaning of self changes. For the original tonic methods, the self points to a global service context. While here, for shard methods the self points to a context for each shard, and for item mutable/readonly methods the self points to the item.

• fn start_simple_dispatch_backend This starts a simple kind of backend tasks, which just listen on the request channel. If you want more complex backend task (e.g. listen on another channel too), you have to create tasks and channels youself.

• struct [<$service DispatchServer>] This defines the real tonic service, and this macro implement it automatically. If you use the start_simple_dispatch_backend which handles this struct already, then you do not need to touch this. But if you need to build backend tasks yourself, then you need to create channels and this struct with their Sender ends by its with_txs() method. See start_simple_dispatch_backend()’s code for example.

Read the DictService example’s source code for a better understanding.