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 | |
24 | namespace brpc { |
25 | class Controller; |
26 | class 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. |
31 | class StreamCreator { |
32 | public: |
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. |
61 | class StreamUserData { |
62 | public: |
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 | |