1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18
19#ifndef BRPC_STREAM_CREATOR_H
20#define BRPC_STREAM_CREATOR_H
21
22#include "brpc/socket_id.h"
23
24namespace brpc {
25class Controller;
26class StreamUserData;
27
28// Abstract creation of "user-level connection" over a RPC-like process.
29// Lifetime of this object should be guaranteed by user during the RPC,
30// generally this object is created before RPC and destroyed after RPC.
31class StreamCreator {
32public:
33 virtual ~StreamCreator() = default;
34
35 // Called when the socket for sending request is about to be created.
36 // If the RPC has retries, this function MAY be called before each retry.
37 // This function would not be called if some preconditions are not
38 // satisfied.
39 // Params:
40 // inout: pointing to the socket to send requests by default,
41 // replaceable by user created ones (or keep as it is). remote_side()
42 // of the replaced socket must be same with the default socket.
43 // The replaced socket should take cntl->connection_type() into account
44 // since the framework sends request by the replaced socket directly
45 // when stream_creator is present.
46 // cntl: contains contexts of the RPC, if there's any error during
47 // replacement, call cntl->SetFailed().
48 virtual StreamUserData* OnCreatingStream(SocketUniquePtr* inout,
49 Controller* cntl) = 0;
50
51 // Called when the StreamCreator is about to destroyed.
52 // This function MUST be called only once at the end of successful RPC
53 // Call to recycle resources.
54 // Params:
55 // cntl: contexts of the RPC
56 virtual void DestroyStreamCreator(Controller* cntl) = 0;
57};
58
59// The Intermediate user data created by StreamCreator to record the context
60// of a specific stream request.
61class StreamUserData {
62public:
63 virtual ~StreamUserData() = default;
64
65 // Called when the streamUserData is about to destroyed.
66 // This function MUST be called to clean up resources if OnCreatingStream
67 // of StreamCreator has returned a valid StreamUserData pointer.
68 // Params:
69 // sending_sock: The socket chosen by OnCreatingStream(), if an error
70 // happens during choosing, the enclosed socket is NULL.
71 // cntl: contexts of the RPC.
72 // error_code: Use this instead of cntl->ErrorCode().
73 // end_of_rpc: true if the RPC is about to destroyed.
74 virtual void DestroyStreamUserData(SocketUniquePtr& sending_sock,
75 Controller* cntl,
76 int error_code,
77 bool end_of_rpc) = 0;
78};
79
80} // namespace brpc
81
82
83#endif // BRPC_STREAM_CREATOR_H
84