thrift/server/TServerFramework.h

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one
0003  * or more contributor license agreements. See the NOTICE file
0004  * distributed with this work for additional information
0005  * regarding copyright ownership. The ASF licenses this file
0006  * to you under the Apache License, Version 2.0 (the
0007  * "License"); you may not use this file except in compliance
0008  * with the License. You may obtain a copy of the License at
0009  *
0010  *   http://www.apache.org/licenses/LICENSE-2.0
0011  *
0012  * Unless required by applicable law or agreed to in writing,
0013  * software distributed under the License is distributed on an
0014  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0015  * KIND, either express or implied. See the License for the
0016  * specific language governing permissions and limitations
0017  * under the License.
0018  */
0019
0020 #ifndef _THRIFT_SERVER_TSERVERFRAMEWORK_H_
0021 #define _THRIFT_SERVER_TSERVERFRAMEWORK_H_ 1
0022
0023 #include <memory>
0024 #include <stdint.h>
0025 #include <thrift/TProcessor.h>
0026 #include <thrift/concurrency/Monitor.h>
0027 #include <thrift/server/TConnectedClient.h>
0028 #include <thrift/server/TServer.h>
0029 #include <thrift/transport/TServerTransport.h>
0030 #include <thrift/transport/TTransport.h>
0031
0032 namespace apache {
0033 namespace thrift {
0034 namespace server {
0035
0036 /**
0037  * TServerFramework provides a single consolidated processing loop for
0038  * servers.  By having a single processing loop, behavior between servers
0039  * is more predictable and maintenance cost is lowered.  Implementations
0040  * of TServerFramework must provide a method to deal with a client that
0041  * connects and one that disconnects.
0042  *
0043  * While this functionality could be rolled directly into TServer, and
0044  * probably should be, it would break the TServer interface contract so
0045  * to maintain backwards compatibility for third party servers, no TServers
0046  * were harmed in the making of this class.
0047  */
0048 class TServerFramework : public TServer {
0049 public:
0050   TServerFramework(
0051       const std::shared_ptr<apache::thrift::TProcessorFactory>& processorFactory,
0052       const std::shared_ptr<apache::thrift::transport::TServerTransport>& serverTransport,
0053       const std::shared_ptr<apache::thrift::transport::TTransportFactory>& transportFactory,
0054       const std::shared_ptr<apache::thrift::protocol::TProtocolFactory>& protocolFactory);
0055
0056   TServerFramework(
0057       const std::shared_ptr<apache::thrift::TProcessor>& processor,
0058       const std::shared_ptr<apache::thrift::transport::TServerTransport>& serverTransport,
0059       const std::shared_ptr<apache::thrift::transport::TTransportFactory>& transportFactory,
0060       const std::shared_ptr<apache::thrift::protocol::TProtocolFactory>& protocolFactory);
0061
0062   TServerFramework(
0063       const std::shared_ptr<apache::thrift::TProcessorFactory>& processorFactory,
0064       const std::shared_ptr<apache::thrift::transport::TServerTransport>& serverTransport,
0065       const std::shared_ptr<apache::thrift::transport::TTransportFactory>& inputTransportFactory,
0066       const std::shared_ptr<apache::thrift::transport::TTransportFactory>& outputTransportFactory,
0067       const std::shared_ptr<apache::thrift::protocol::TProtocolFactory>& inputProtocolFactory,
0068       const std::shared_ptr<apache::thrift::protocol::TProtocolFactory>& outputProtocolFactory);
0069
0070   TServerFramework(
0071       const std::shared_ptr<apache::thrift::TProcessor>& processor,
0072       const std::shared_ptr<apache::thrift::transport::TServerTransport>& serverTransport,
0073       const std::shared_ptr<apache::thrift::transport::TTransportFactory>& inputTransportFactory,
0074       const std::shared_ptr<apache::thrift::transport::TTransportFactory>& outputTransportFactory,
0075       const std::shared_ptr<apache::thrift::protocol::TProtocolFactory>& inputProtocolFactory,
0076       const std::shared_ptr<apache::thrift::protocol::TProtocolFactory>& outputProtocolFactory);
0077
0078   ~TServerFramework() override;
0079
0080   /**
0081    * Accept clients from the TServerTransport and add them for processing.
0082    * Call stop() on another thread to interrupt processing
0083    * and return control to the caller.
0084    * Post-conditions (return guarantees):
0085    *   The serverTransport will be closed.
0086    */
0087   void serve() override;
0088
0089   /**
0090    * Interrupt serve() so that it meets post-conditions and returns.
0091    */
0092   void stop() override;
0093
0094   /**
0095    * Get the concurrent client limit.
0096    * \returns the concurrent client limit
0097    */
0098   virtual int64_t getConcurrentClientLimit() const;
0099
0100   /**
0101    * Get the number of currently connected clients.
0102    * \returns the number of currently connected clients
0103    */
0104   virtual int64_t getConcurrentClientCount() const;
0105
0106   /**
0107    * Get the highest number of concurrent clients.
0108    * \returns the highest number of concurrent clients
0109    */
0110   virtual int64_t getConcurrentClientCountHWM() const;
0111
0112   /**
0113    * Set the concurrent client limit.  This can be changed while
0114    * the server is serving however it will not necessarily be
0115    * enforced until the next client is accepted and added.  If the
0116    * limit is lowered below the number of connected clients, no
0117    * action is taken to disconnect the clients.
0118    * The default value used if this is not called is INT64_MAX.
0119    * \param[in]  newLimit  the new limit of concurrent clients
0120    * \throws std::invalid_argument if newLimit is less than 1
0121    */
0122   virtual void setConcurrentClientLimit(int64_t newLimit);
0123
0124 protected:
0125   /**
0126    * A client has connected.  The implementation is responsible for managing the
0127    * lifetime of the client object.  This is called during the serve() thread,
0128    * therefore a failure to return quickly will result in new client connection
0129    * delays.
0130    *
0131    * \param[in]  pClient  the newly connected client
0132    */
0133   virtual void onClientConnected(const std::shared_ptr<TConnectedClient>& pClient) = 0;
0134
0135   /**
0136    * A client has disconnected.
0137    * When called:
0138    *   The server no longer tracks the client.
0139    *   The client TTransport has already been closed.
0140    *   The implementation must not delete the pointer.
0141    *
0142    * \param[in]  pClient  the disconnected client
0143    */
0144   virtual void onClientDisconnected(TConnectedClient* pClient) = 0;
0145
0146 private:
0147   /**
0148    * Common handling for new connected clients.  Implements concurrent
0149    * client rate limiting after onClientConnected returns by blocking the
0150    * serve() thread if the limit has been reached.
0151    */
0152   void newlyConnectedClient(const std::shared_ptr<TConnectedClient>& pClient);
0153
0154   /**
0155    * Smart pointer client deletion.
0156    * Calls onClientDisconnected and then deletes pClient.
0157    */
0158   void disposeConnectedClient(TConnectedClient* pClient);
0159
0160   /**
0161    * Monitor for limiting the number of concurrent clients.
0162    */
0163   apache::thrift::concurrency::Monitor mon_;
0164
0165   /**
0166    * The number of concurrent clients.
0167    */
0168   int64_t clients_;
0169
0170   /**
0171    * The high water mark of concurrent clients.
0172    */
0173   int64_t hwm_;
0174
0175   /**
0176    * The limit on the number of concurrent clients.
0177    */
0178   int64_t limit_;
0179 };
0180 }
0181 }
0182 } // apache::thrift::server
0183
0184 #endif // #ifndef _THRIFT_SERVER_TSERVERFRAMEWORK_H_