/** * @file _httplibcurl.h * @brief Declarations for internal class providing libcurl transport. * * $LicenseInfo:firstyear=2012&license=viewerlgpl$ * Second Life Viewer Source Code * Copyright (C) 2012-2014, Linden Research, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; * version 2.1 of the License only. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA * * Linden Research, Inc., 945 Battery Street, San Francisco, CA 94111 USA * $/LicenseInfo$ */ #ifndef _LLCORE_HTTP_LIBCURL_H_ #define _LLCORE_HTTP_LIBCURL_H_ #include "linden_common.h" // Modifies curl/curl.h interfaces #include <curl/curl.h> #include <curl/multi.h> #include <set> #include "httprequest.h" #include "_httpservice.h" #include "_httpinternal.h" namespace LLCore { class HttpPolicy; class HttpOpRequest; class HttpHeaders; /// Implements libcurl-based transport for an HttpService instance. /// /// Threading: Single-threaded. Other than for construction/destruction, /// all methods are expected to be invoked in a single thread, typically /// a worker thread of some sort. class HttpLibcurl { public: HttpLibcurl(HttpService * service); virtual ~HttpLibcurl(); private: HttpLibcurl(const HttpLibcurl &); // Not defined void operator=(const HttpLibcurl &); // Not defined public: typedef boost::shared_ptr<HttpOpRequest> opReqPtr_t; /// Give cycles to libcurl to run active requests. Completed /// operations (successful or failed) will be retried or handed /// over to the reply queue as final responses. /// /// @return Indication of how long this method is /// willing to wait for next service call. /// /// Threading: called by worker thread. HttpService::ELoopSpeed processTransport(); /// Add request to the active list. Caller is expected to have /// provided us with a reference count on the op to hold the /// request. (No additional references will be added.) /// /// Threading: called by worker thread. void addOp(const opReqPtr_t & op); /// One-time call to set the number of policy classes to be /// serviced and to create the resources for each. Value /// must agree with HttpPolicy::setPolicies() call. /// /// Threading: called by init thread. void start(int policy_count); /// Synchronously stop libcurl operations. All active requests /// are canceled and removed from libcurl's handling. Easy /// handles are detached from their multi handles and released. /// Multi handles are also released. Canceled requests are /// completed with canceled status and made available on their /// respective reply queues. /// /// Can be restarted with a start() call. /// /// Threading: called by worker thread. void shutdown(); /// Return global and per-class counts of active requests. /// /// Threading: called by worker thread. int getActiveCount() const; int getActiveCountInClass(int policy_class) const; /// Attempt to cancel a request identified by handle. /// /// Interface shadows HttpService's method. /// /// @return True if handle was found and operation canceled. /// /// Threading: called by worker thread. bool cancel(HttpHandle handle); /// Informs transport that a particular policy class has had /// options changed and so should effect any transport state /// change necessary to effect those changes. Used mainly for /// initialization and dynamic option setting. /// /// Threading: called by worker thread. void policyUpdated(int policy_class); /// Allocate a curl handle for caller. May be freed using /// either the freeHandle() method or calling curl_easy_cleanup() /// directly. /// /// @return Libcurl handle (CURL *) or NULL on allocation /// problem. Handle will be in curl_easy_reset() /// condition. /// /// Threading: callable by worker thread. /// /// Deprecation: Expect this to go away after _httpoprequest is /// refactored bringing code into this class. CURL * getHandle() { return mHandleCache.getHandle(); } protected: /// Invoked when libcurl has indicated a request has been processed /// to completion and we need to move the request to a new state. bool completeRequest(CURLM * multi_handle, CURL * handle, CURLcode status); /// Invoked to cancel an active request, mainly during shutdown /// and destroy. void cancelRequest(const opReqPtr_t &op); protected: typedef std::set<opReqPtr_t> active_set_t; /// Simple request handle cache for libcurl. /// /// Handle creation is somewhat slow and chunky in libcurl and there's /// a pretty good speedup to be had from handle re-use. So, a simple /// vector is kept of 'freed' handles to be reused as needed. When /// that is empty, the first freed handle is kept as a template for /// handle duplication. This is still faster than creation from nothing. /// And when that fails, we init fresh from curl_easy_init(). /// /// Handles allocated with getHandle() may be freed with either /// freeHandle() or curl_easy_cleanup(). Choice may be dictated /// by thread constraints. /// /// Threading: Single-threaded. May only be used by a single thread, /// typically the worker thread. If freeing requests' handles in an /// unknown threading context, use curl_easy_cleanup() for safety. class HandleCache { public: HandleCache(); ~HandleCache(); private: HandleCache(const HandleCache &); // Not defined void operator=(const HandleCache &); // Not defined public: /// Allocate a curl handle for caller. May be freed using /// either the freeHandle() method or calling curl_easy_cleanup() /// directly. /// /// @return Libcurl handle (CURL *) or NULL on allocation /// problem. /// /// Threading: Single-thread (worker) only. CURL * getHandle(); /// Free a libcurl handle acquired by whatever means. Thread /// safety is left to the caller. /// /// Threading: Single-thread (worker) only. void freeHandle(CURL * handle); protected: typedef std::vector<CURL *> handle_cache_t; protected: CURL * mHandleTemplate; // Template for duplicating new handles handle_cache_t mCache; // Cache of old handles }; // end class HandleCache protected: HttpService * mService; // Simple reference, not owner HandleCache mHandleCache; // Handle allocator, owner active_set_t mActiveOps; int mPolicyCount; CURLM ** mMultiHandles; // One handle per policy class int * mActiveHandles; // Active count per policy class bool * mDirtyPolicy; // Dirty policy update waiting for stall (per pc) }; // end class HttpLibcurl } // end namespace LLCore #endif // _LLCORE_HTTP_LIBCURL_H_