1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
// Copyright 2020-2022 The Defold Foundation
// Copyright 2014-2020 King
// Copyright 2009-2014 Ragnar Svensson, Christian Murray
// Licensed under the Defold License version 1.0 (the "License"); you may not use
// this file except in compliance with the License.
//
// You may obtain a copy of the License, together with FAQs at
// https://www.defold.com/license
//
// Unless required by applicable law or agreed to in writing, software distributed
// under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
// CONDITIONS OF ANY KIND, either express or implied. See the License for the
// specific language governing permissions and limitations under the License.
#ifndef DMSDK_CONNECTION_POOL
#define DMSDK_CONNECTION_POOL
#include <stdint.h>
// Cannot forward declare enums
#include <dmsdk/dlib/socket.h>
// Please note that the underlying types may change at our discretion
namespace dmSSLSocket
{
typedef struct SSLSocket* Socket;
}
/*# SDK Connection pool API documentation
*
* Connection pool
*
* @document
* @name Connection Pool
* @namespace dmConnectionPool
* @path engine/dlib/src/dmsdk/dlib/connection_pool.h
*/
namespace dmConnectionPool
{
/*# Connection pool handle
* @typedef
* @name HPool
*/
typedef struct ConnectionPool* HPool;
/*# Connection handle
* @typedef
* @name HConnection
*/
typedef uint32_t HConnection;
/*# result enumeration
* Result enumeration.
* @enum
* @name dmConnectionPool::Result
* @member dmConnectionPool::RESULT_OK 0
* @member dmConnectionPool::RESULT_OUT_OF_RESOURCES -1
* @member dmConnectionPool::RESULT_SOCKET_ERROR -2
* @member dmConnectionPool::RESULT_HANDSHAKE_FAILED -3
* @member dmConnectionPool::RESULT_SHUT_DOWN -4
*/
enum Result
{
RESULT_OK = 0,
RESULT_OUT_OF_RESOURCES = -1,
RESULT_SOCKET_ERROR = -2,
RESULT_HANDSHAKE_FAILED = -3,
RESULT_SHUT_DOWN = -4,
};
/*#
* Creation parameters
* @struct
* @name dmConnectionPool::Params
* @member m_MaxConnections [type:int] Max connection in pool
* @member m_MaxKeepAlive [type:int] Default max-keep-alive time in seconds
*/
struct Params
{
Params()
{
m_MaxConnections = 64;
m_MaxKeepAlive = 10;
}
uint32_t m_MaxConnections;
uint32_t m_MaxKeepAlive;
};
/*#
* Create a new connection pool
* @name dmConnectionPool::New
* @param params
* @param pool [type:dmConnectionPool::HPool*] pool (out)
* @return dmConnectionPool::RESULT_OK on success
*/
Result New(const Params* params, HPool* pool);
/*#
* Delete connnection pool
* @name dmConnectionPool::Delete
* @param pool [type:dmConnectionPool::HPool] pool
* @return dmConnectionPool::RESULT_OK on success
*/
Result Delete(HPool pool);
/*#
* Connection to a host/port
* @name dmConnectionPool::Dial
* @param pool [type:dmConnectionPool::HPool] pool
* @param host [type:const char*] host
* @param port [type:uint16_t] port
* @param ssl [type:bool] true for ssl connection
* @param timeout [type:int] The timeout (micro seconds) for the connection and ssl handshake
* @param connection [type:dmConnectionPool::HConnection*] connection (out)
* @param sock_res [type:dmSocket::Result*] socket-result code on failure
* @return dmConnectionPool::RESULT_OK on success
*/
Result Dial(HPool pool, const char* host, uint16_t port, bool ssl, int timeout, HConnection* connection, dmSocket::Result* sock_res);
/*#
* Connection to a host/port
* @name dmConnectionPool::Dial
* @param pool [type:dmConnectionPool::HPool] pool
* @param host [type:const char*] host
* @param port [type:uint16_t] port
* @param ssl [type:bool] true for ssl connection
* @param timeout [type:int] The timeout (micro seconds) for the connection and ssl handshake
* @param cancelflag [type:int*] If set and not null, will make the request early out
* @param connection [type:dmConnectionPool::HConnection*] connection (out)
* @param sock_res [type:dmSocket::Result*] socket-result code on failure
* @return dmConnectionPool::RESULT_OK on success
*/
Result Dial(HPool pool, const char* host, uint16_t port, bool ssl, int timeout, int* cancelflag, HConnection* connection, dmSocket::Result* sock_res);
/*#
* Return connection to pool
* @name dmConnectionPool::Return
* @param pool [type:dmConnectionPool::HPool] pool
* @param connection [type:dmConnectionPool::HConnection]
*/
void Return(HPool pool, HConnection connection);
/*#
* Close connection. Use this function whenever an error occur in eg http.
* @name dmConnectionPool::Close
* @param pool [type:dmConnectionPool::HPool] pool
* @param connection [type:dmConnectionPool::HConnection]
*/
void Close(HPool pool, HConnection connection);
/*#
* Get socket for connection
* @name dmConnectionPool::GetSocket
* @param pool [type:dmConnectionPool::HPool] pool
* @param connection [type:dmConnectionPool::HConnection]
* @return [type:dmSocket::Socket] on success
*/
dmSocket::Socket GetSocket(HPool pool, HConnection connection);
/*#
* Get secure socket.
* @name dmConnectionPool::GetSSLSocket
* @param pool [type:dmConnectionPool::HPool] pool
* @param connection [type:dmConnectionPool::HConnection]
* @return [type:dmSSLSocket::Socket] on success
*/
dmSSLSocket::Socket GetSSLSocket(HPool pool, HConnection connection);
/**
* Get reuse count for a connection
* @name dmConnectionPool::GetReuseCount
* @param pool [type:dmConnectionPool::HPool] pool
* @param connection [type:dmConnectionPool::HConnection]
* @return reuse count
*/
uint32_t GetReuseCount(HPool pool, HConnection connection);
/*#
* Shuts down all open sockets in the pool and block new connection attempts. The function can be
* called repeatedly on the same pool until it returns no more connections in use.
*
* @name dmConnectionPool::Shutdown
* @param pool [type:dmConnectionPool::HPool] pool
* @param how [type:dmSocket::ShutdownType] shutdown type to pass to socket shutdown function
* @return current number of connections in use
*/
uint32_t Shutdown(HPool pool, dmSocket::ShutdownType how);
}
#endif // #ifndef DMSDK_CONNECTION_POOL