WebSocket++ 0.8.2
C++ websocket client/server library
pool.hpp
1/*
2 * Copyright (c) 2014, Peter Thorson. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 * * Redistributions of source code must retain the above copyright
7 * notice, this list of conditions and the following disclaimer.
8 * * Redistributions in binary form must reproduce the above copyright
9 * notice, this list of conditions and the following disclaimer in the
10 * documentation and/or other materials provided with the distribution.
11 * * Neither the name of the WebSocket++ Project nor the
12 * names of its contributors may be used to endorse or promote products
13 * derived from this software without specific prior written permission.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 * ARE DISCLAIMED. IN NO EVENT SHALL PETER THORSON BE LIABLE FOR ANY
19 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
22 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 *
26 */
27
28#ifndef WEBSOCKETPP_MESSAGE_BUFFER_ALLOC_HPP
29#define WEBSOCKETPP_MESSAGE_BUFFER_ALLOC_HPP
30
31#include <websocketpp/common/memory.hpp>
32
33#include <string>
34
35namespace websocketpp {
36namespace message_buffer {
37
38/* # message:
39 * object that stores a message while it is being sent or received. Contains
40 * the message payload itself, the message header, the extension data, and the
41 * opcode.
42 *
43 * # connection_message_manager:
44 * An object that manages all of the message_buffers associated with a given
45 * connection. Implements the get_message_buffer(size) method that returns
46 * a message buffer at least size bytes long.
47 *
48 * Message buffers are reference counted with shared ownership semantics. Once
49 * requested from the manager the requester and it's associated downstream code
50 * may keep a pointer to the message indefinitely at a cost of extra resource
51 * usage. Once the reference count drops to the point where the manager is the
52 * only reference the messages is recycled using whatever method is implemented
53 * in the manager.
54 *
55 * # endpoint_message_manager:
56 * An object that manages connection_message_managers. Implements the
57 * get_message_manager() method. This is used once by each connection to
58 * request the message manager that they are supposed to use to manage message
59 * buffers for their own use.
60 *
61 * TYPES OF CONNECTION_MESSAGE_MANAGERS
62 * - allocate a message with the exact size every time one is requested
63 * - maintain a pool of pre-allocated messages and return one when needed.
64 * Recycle previously used messages back into the pool
65 *
66 * TYPES OF ENDPOINT_MESSAGE_MANAGERS
67 * - allocate a new connection manager for each connection. Message pools
68 * become connection specific. This increases memory usage but improves
69 * concurrency.
70 * - allocate a single connection manager and share a pointer to it with all
71 * connections created by this endpoint. The message pool will be shared
72 * among all connections, improving memory usage and performance at the cost
73 * of reduced concurrency
74 */
75
76/// Custom deleter for use in shared_ptrs to message.
77/**
78 * This is used to catch messages about to be deleted and offer the manager the
79 * ability to recycle them instead. Message::recycle will return true if it was
80 * successfully recycled and false otherwise. In the case of exceptions or error
81 * this deleter frees the memory.
82 */
83template <typename T>
84void message_deleter(T* msg) {
85 try {
86 if (!msg->recycle()) {
87 delete msg;
88 }
89 } catch (...) {
90 // TODO: is there a better way to ensure this function doesn't throw?
91 delete msg;
92 }
93}
94
95/// Represents a buffer for a single WebSocket message.
96/**
97 *
98 *
99 */
100template <typename con_msg_manager>
101class message {
102public:
103 typedef lib::shared_ptr<message> ptr;
104
105 typedef typename con_msg_manager::weak_ptr con_msg_man_ptr;
106
107 message(con_msg_man_ptr manager, size_t size = 128)
108 : m_manager(manager)
109 , m_payload(size) {}
110
111 frame::opcode::value get_opcode() const {
112 return m_opcode;
113 }
114 const std::string& get_header() const {
115 return m_header;
116 }
117 const std::string& get_extension_data() const {
118 return m_extension_data;
119 }
120 const std::string& get_payload() const {
121 return m_payload;
122 }
123
124 /// Recycle the message
125 /**
126 * A request to recycle this message was received. Forward that request to
127 * the connection message manager for processing. Errors and exceptions
128 * from the manager's recycle member function should be passed back up the
129 * call chain. The caller to message::recycle will deal with them.
130 *
131 * Recycle must *only* be called by the message shared_ptr's destructor.
132 * Once recycled successfully, ownership of the memory has been passed to
133 * another system and must not be accessed again.
134 *
135 * @return true if the message was successfully recycled, false otherwise.
136 */
137 bool recycle() {
138 typename con_msg_manager::ptr shared = m_manager.lock();
139
140 if (shared) {
141 return shared->(recycle(this));
142 } else {
143 return false;
144 }
145 }
146private:
147 con_msg_man_ptr m_manager;
148
149 frame::opcode::value m_opcode;
150 std::string m_header;
151 std::string m_extension_data;
152 std::string m_payload;
153};
154
155namespace alloc {
156
157/// A connection message manager that allocates a new message for each
158/// request.
159template <typename message>
160class con_msg_manager {
161public:
162 typedef lib::shared_ptr<con_msg_manager> ptr;
163 typedef lib::weak_ptr<con_msg_manager> weak_ptr;
164
165 typedef typename message::ptr message_ptr;
166
167 /// Get a message buffer with specified size
168 /**
169 * @param size Minimum size in bytes to request for the message payload.
170 *
171 * @return A shared pointer to a new message with specified size.
172 */
173 message_ptr get_message(size_t size) const {
174 return lib::make_shared<message>(size);
175 }
176
177 /// Recycle a message
178 /**
179 * This method shouldn't be called. If it is, return false to indicate an
180 * error. The rest of the method recycle chain should notice this and free
181 * the memory.
182 *
183 * @param msg The message to be recycled.
184 *
185 * @return true if the message was successfully recycled, false otherwse.
186 */
187 bool recycle(message * msg) {
188 return false;
189 }
190};
191
192/// An endpoint message manager that allocates a new manager for each
193/// connection.
194template <typename con_msg_manager>
196public:
197 typedef typename con_msg_manager::ptr con_msg_man_ptr;
198
199 /// Get a pointer to a connection message manager
200 /**
201 * @return A pointer to the requested connection message manager.
202 */
203 con_msg_man_ptr get_manager() const {
204 return lib::make_shared<con_msg_manager>();
205 }
206};
207
208} // namespace alloc
209
210namespace pool {
211
212/// A connection messages manager that maintains a pool of messages that is
213/// used to fulfill get_message requests.
214class con_msg_manager {
215
216};
217
218/// An endpoint manager that maintains a shared pool of connection managers
219/// and returns an appropriate one for the requesting connection.
221
222};
223
224} // namespace pool
225
226} // namespace message_buffer
227} // namespace websocketpp
228
229#endif // WEBSOCKETPP_MESSAGE_BUFFER_ALLOC_HPP
message_ptr get_message(size_t size) const
Get a message buffer with specified size.
Definition: pool.hpp:173
bool recycle(message *)
Recycle a message.
Definition: alloc.hpp:80
con_msg_man_ptr get_manager() const
Get a pointer to a connection message manager.
Definition: alloc.hpp:96
bool recycle()
Recycle the message.
Definition: pool.hpp:137
Namespace for the WebSocket++ project.