1+ #ifndef CPR_CONNECTION_POOL_H
2+ #define CPR_CONNECTION_POOL_H
3+
4+ #include < curl/curl.h>
5+ #include < memory>
6+ #include < mutex>
7+
8+ namespace cpr {
9+ /* *
10+ * cpr connection pool implementation for sharing connections between HTTP requests.
11+ *
12+ * The ConnectionPool enables connection reuse across multiple HTTP requests to the same host,
13+ * which can significantly improve performance by avoiding the overhead of establishing new
14+ * connections for each request. It uses libcurl's CURLSH (share) interface to manage
15+ * connection sharing in a thread-safe manner.
16+ *
17+ * Example:
18+ * ```cpp
19+ * // Create a connection pool
20+ * cpr::ConnectionPool pool;
21+ *
22+ * // Use the pool with requests to reuse connections
23+ * cpr::Response r1 = cpr::Get(cpr::Url{"http://example.com/api/data"}, pool);
24+ * cpr::Response r2 = cpr::Get(cpr::Url{"http://example.com/api/more"}, pool);
25+ *
26+ * // Or with async requests
27+ * auto future1 = cpr::GetAsync(cpr::Url{"http://example.com/api/data"}, pool);
28+ * auto future2 = cpr::GetAsync(cpr::Url{"http://example.com/api/more"}, pool);
29+ * ```
30+ **/
31+ class ConnectionPool {
32+ public:
33+ /* *
34+ * Creates a new connection pool with shared connection state.
35+ * Initializes the underlying CURLSH handle and sets up thread-safe locking mechanisms.
36+ **/
37+ ConnectionPool ();
38+
39+ /* *
40+ * Copy constructor - creates a new connection pool sharing the same connection state.
41+ * Multiple ConnectionPool instances can share the same underlying connection pool.
42+ **/
43+ ConnectionPool (const ConnectionPool&) = default ;
44+
45+ /* *
46+ * Copy assignment operator is deleted to prevent accidental copying.
47+ * Use the copy constructor if you need to share the connection pool.
48+ **/
49+ ConnectionPool& operator =(const ConnectionPool&) = delete ;
50+
51+ /* *
52+ * Configures a CURL easy handle to use this connection pool.
53+ * This method sets up the easy handle to participate in connection sharing
54+ * managed by this pool.
55+ *
56+ * @param easy_handler The CURL easy handle to configure for connection sharing.
57+ **/
58+ void SetupHandler (CURL* easy_handler) const ;
59+
60+ private:
61+ /* *
62+ * Thread-safe mutex used for synchronizing access to shared connections.
63+ * This mutex is passed to libcurl's locking callbacks to ensure thread safety
64+ * when multiple threads access the same connection pool. It's declared first
65+ * to ensure it's destroyed last, after the CURLSH handle that references it.
66+ **/
67+ std::shared_ptr<std::mutex> connection_mutex_;
68+
69+ /* *
70+ * Shared CURL handle (CURLSH) that manages the actual connection sharing.
71+ * This handle maintains the pool of reusable connections and is configured
72+ * with appropriate locking callbacks for thread safety. The shared_ptr uses
73+ * a custom deleter that safely resets the lock/unlock callbacks before
74+ * calling curl_share_cleanup() to prevent use-after-free issues during destruction.
75+ * Declared last to ensure it's destroyed first, before the mutex it references.
76+ **/
77+ std::shared_ptr<CURLSH> curl_sh_;
78+ };
79+ } // namespace cpr
80+ #endif
0 commit comments