thrift/transport/TServerTransport.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_TRANSPORT_TSERVERTRANSPORT_H_
0021 #define _THRIFT_TRANSPORT_TSERVERTRANSPORT_H_ 1
0022
0023 #include <thrift/transport/TTransport.h>
0024 #include <thrift/transport/TTransportException.h>
0025
0026 namespace apache {
0027 namespace thrift {
0028 namespace transport {
0029
0030 /**
0031  * Server transport framework. A server needs to have some facility for
0032  * creating base transports to read/write from.  The server is expected
0033  * to keep track of TTransport children that it creates for purposes of
0034  * controlling their lifetime.
0035  */
0036 class TServerTransport {
0037 public:
0038   virtual ~TServerTransport() = default;
0039
0040   /**
0041    * Whether this transport is open.
0042    */
0043   virtual bool isOpen() const { return false; }
0044
0045   /**
0046    * Starts the server transport listening for new connections. Prior to this
0047    * call most transports will not return anything when accept is called.
0048    *
0049    * @throws TTransportException if we were unable to listen
0050    */
0051   virtual void listen() {}
0052
0053   /**
0054    * Gets a new dynamically allocated transport object and passes it to the
0055    * caller. Note that it is the explicit duty of the caller to free the
0056    * allocated object. The returned TTransport object must always be in the
0057    * opened state. nullptr should never be returned, instead an Exception should
0058    * always be thrown.
0059    *
0060    * @return A new TTransport object
0061    * @throws TTransportException if there is an error
0062    */
0063   std::shared_ptr<TTransport> accept() {
0064     std::shared_ptr<TTransport> result = acceptImpl();
0065     if (!result) {
0066       throw TTransportException("accept() may not return nullptr");
0067     }
0068     return result;
0069   }
0070
0071   /**
0072    * For "smart" TServerTransport implementations that work in a multi
0073    * threaded context this can be used to break out of an accept() call.
0074    * It is expected that the transport will throw a TTransportException
0075    * with the INTERRUPTED error code.
0076    *
0077    * This will not make an attempt to interrupt any TTransport children.
0078    */
0079   virtual void interrupt() {}
0080
0081   /**
0082    * This will interrupt the children created by the server transport.
0083    * allowing them to break out of any blocking data reception call.
0084    * It is expected that the children will throw a TTransportException
0085    * with the INTERRUPTED error code.
0086    */
0087   virtual void interruptChildren() {}
0088
0089   /**
0090   * Utility method
0091   *
0092   * @return server socket file descriptor
0093   * @throw TTransportException If an error occurs
0094   */
0095
0096   virtual THRIFT_SOCKET getSocketFD() { return -1; }
0097
0098   /**
0099    * Closes this transport such that future calls to accept will do nothing.
0100    */
0101   virtual void close() = 0;
0102
0103 protected:
0104   TServerTransport() = default;
0105
0106   /**
0107    * Subclasses should implement this function for accept.
0108    *
0109    * @return A newly allocated TTransport object
0110    * @throw TTransportException If an error occurs
0111    */
0112   virtual std::shared_ptr<TTransport> acceptImpl() = 0;
0113 };
0114 }
0115 }
0116 } // apache::thrift::transport
0117
0118 #endif // #ifndef _THRIFT_TRANSPORT_TSERVERTRANSPORT_H_