X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FSocketProtocol.hh;h=b41fccb8b05e182579462235abe3db3a3e5f30d0;hb=b8ca4a544cce3e6023bb56b712a03d6362f2bb79;hp=6ce9c6119bb52f48c2f7031d1cc258fe535cd6e8;hpb=c13146edc1b57cc60f102bcfd1a7a602ecec261f;p=senf.git diff --git a/Socket/SocketProtocol.hh b/Socket/SocketProtocol.hh index 6ce9c61..b41fccb 100644 --- a/Socket/SocketProtocol.hh +++ b/Socket/SocketProtocol.hh @@ -1,9 +1,9 @@ // $Id$ // // Copyright (C) 2006 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) -// Stefan Bund +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY +// Stefan Bund // // This program is free software; you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by @@ -22,11 +22,6 @@ /** \file \brief SocketProtocol and ConcreteSocketProtocol public header - - \idea We should optimize the protocol handling. Allocating a protocol instance for every socket - body seems quite wasteful. We could derive SocketPolicy from SocketBody (probably privately, - since private inheritance models more of 'has a' than 'is a'). This would allow to reduce - the number of heap-allocations per socket to one which is good. */ // The private inheritance idea should indeed work very well: We just need to change the @@ -37,7 +32,19 @@ /** \defgroup protocol_group The Protocol Classes - \image html Protocols.png +
+ \ref SocketProtocol + \ref UNSocketProtocol + \ref PacketSocketProtocol + \ref ConcreteSocketProtocol + \ref BSDSocketProtocol + \ref DatagramSocketProtocol + \ref TCPSocketProtocol + \ref UNDatagramSocketProtocol + \ref AddressableBSDSocketProtocol + \ref TCPv4SocketProtocol +
+ \htmlonly Protocols \endhtmlonly The socket handle classes and templates only implement the most important socket API methods using the policy framework. To access the complete API, the protocol interface is @@ -50,16 +57,13 @@ protocols are implemented using a simple multiple-inheritance hierarchy as shown above. Since the protocol class is protocol specific (how intelligent ...), the protocol class also - defines the complete socket policy to be used with it's protocol. Complete meaning, that every - policy axis must be assigned it's the most specific (that is derived) policy class to be used - with the protocol. + defines the \e complete socket policy to be used with it's protocol. Complete meaning, that + every policy axis must be assigned it's the most specific (that is derived) policy class to be + used with the protocol and that no policy axis is allowed to be left unspecified. \see \ref handle_group \n \ref policy_group - - \todo Complete the protocol interface implementations. Better distribution of members to - protocol facets and more precise distribution of functionality among the facets. */ /** \defgroup concrete_protocol_group Protocol Implementations (Concrete Protocol Classes) @@ -85,8 +89,8 @@ accessibility of the socket body from all facets. */ -#ifndef HH_SocketProtocol_ -#define HH_SocketProtocol_ 1 +#ifndef HH_SENF_Socket_SocketProtocol_ +#define HH_SENF_Socket_SocketProtocol_ 1 // Custom includes #include @@ -111,7 +115,8 @@ namespace senf { \attention SocketProtocol must \e always be inherited using public \e virtual inheritance. */ - class SocketProtocol : boost::noncopyable + class SocketProtocol + : boost::noncopyable { public: /////////////////////////////////////////////////////////////////////////// @@ -131,31 +136,30 @@ namespace senf { ///@} /////////////////////////////////////////////////////////////////////////// - SocketBody & body() const; ///< Access the socket body - /**< \todo we don't need body(), we should better provide a - handle() member which will return a simple FIleHandle - object (we cannot return some other derived class since - we don't know the Protocol or Policy at this point) */ virtual SocketPolicyBase const & policy() const = 0; - ///< Access the policy instance + ///< Access the policy instance /////////////////////////////////////////////////////////////////////////// // Virtual interface - virtual std::auto_ptr clone() const = 0; - ///< Polymorphically return a copy of this protocol class - /**< This member will create a new copy of the protocol - class on the heap. - \attention This member must be implemented in every \e - leaf protocol class to return a new instance of the - appropriate type. */ virtual unsigned available() const = 0; - ///< Return number of bytes available for reading without - ///< blocking + ///< Return (maximum) number of bytes available for reading + ///< without < blocking /**< This member will check in a (very, sigh) protocol - dependent way, how many bytes are guaranteed to be - readable from the socket without blocking even if the - socket is blocking. */ + dependent way, how many bytes may be read from a socket + in a single (non-blocking) read operation. If the + socket does not support reading (viz. NotReadablePolicy + is set), this member should always return \c 0. + + Depending on the protocol, it may not be possible to + return a good value. In this case, an upper bound may + be returned (e.g.: When reading from a socket which + returns ethernet frames, returning 1500 from + available() is ok). However, this should only be done + as a last resort. Also beware, that this number should + not be too large since the socket layer will always + need to allocate that number of bytes for the data to + be read. */ virtual bool eof() const = 0; ///< Check for end-of-file condition /**< This is another check which (like available()) is @@ -163,6 +167,22 @@ namespace senf { \c true only, if at end-of-file. If the protocol does not support the notion of EOF, this member should always return \c false. */ + + virtual void close(); ///< Close socket + /**< This override will automatically \c shutdown() the + socket whenever it is closed. + \throws senf::SystemException + \fixme Move into (at least) BSDSOcketProtocol */ + + virtual void terminate() const; ///< Forcibly close socket + /**< This override will automatically \c shutdown() the + socket whenever it is called. Additionally it will + disable SO_LINGER to ensure, that v_terminate will not + block. Like the overriden method, this member will ignore + failures and will never throw. It is therefore safe to be + called from a destructor. + \fixme Move into (at least) BSDSocketProtocol */ + virtual void state(SocketStateMap & map, unsigned lod) const; ///< Return socket state information /**< This member is called to add state information to the @@ -172,7 +192,7 @@ namespace senf { \a lod value with a default value of 0. The interpretation of the \a lod value is completely implementation defined. - + Every class derived from SocketProtocol should reimplement state(). The reimplemented method should call (all) baseclass-implementations of this @@ -183,45 +203,67 @@ namespace senf { keys are interpreted as hierarchical strings with '.' as a separator (like hostnames or struct or class members). They are automatically sorted correctly. - + The values are std:string with one additional feature: they allow assignment or conversion from *any* type as long as that type is streamable. This simplifies assigning non-string values to the map: - + \code - map["socket.protocol.ip.address"] = peer(); - map["socket.protocol.tcp.backlog"] = backlog(); + map["socket.protocol.ip.address"] << peer(); + map["socket.protocol.tcp.backlog"] << backlog(); \endcode - + This will work even if peer() returns an ip-address object or backlog() returns an integer. The values are automatically converted to their string representation. - - The operator "+=" also has been reimplemented to - simplify adding multiple values to a single entry: It - will automatically add a ", " separator if the string - is non-empty. */ + + Additionally, if the slot the date is written to is not + empty, the \<\< operator will add add a comma + as separator. */ protected: + FileHandle fh() const; ///< Get a FileHandle for this instance + /**< This member will re turn a FileHandle instance for this + protocol instance. You may cast this FileHandle + instance to a ClientSocketHandle / ServerSocketHandle + as long as you know some of the socket policy using + static_socket_cast or dynamic_socket_cast */ + + int fd() const; ///< Get file descriptor + /**< Returns the file descriptor this protocol instance + references. This is the same as fh().fd() but + is implemented here since it is needed so often. */ + + void fd(int) const; ///< Initialize file descriptor + /**< Assigns the file descriptor to the file handle, this + protocol instance references. Only valid, if the file + handle has not yet been assigned any descriptor (To + change the file descriptor association later, use \c + ::dup2()). */ private: - // backpointer to owning SocketBody instance - SocketBody * body_; - friend class SocketBody; - }; + virtual std::auto_ptr clone(bool isServer) const = 0; + virtual std::auto_ptr clone(int fd, bool isServer) const = 0; + virtual SocketBody & body() const = 0; + friend class SocketBody; + }; + + template class ClientSocketHandle; + template class ServerSocketHandle; /** \brief Concrete Socket Protocol implementation base class ConcreteSocketProtocol is the base class of a concrete socket protocol implementation. The final protocol class must inherit from ConcreteSocketProtocol. The template argument \a - SocketPolicy must be set to the complete socket policy of the protocol. + SocketPolicy must be set to the complete socket policy of the protocol. \a Self is the name + of the final protocol class which inherits this class. A protocol implementation may define the protocol interface directly. It can also (additionally) make use of multiple inheritance to combine a set of protocol facets into a specific protocol implementation (i.e. TCPv4SocketProtocol inherits from - ConcreteSocketProtocol and from the protocol facets IPv4Protocol, TCPProtocol, + ConcreteSocketProtocol and from the protocol facets IPv4SocketProtocol, TCPSocketProtocol, BSDSocketProtocol and AddressableBSDSocketProtocol). The protocol facets are not concrete protocols themselves, they are combined to build concrete protocols. This structure will remove a lot of code duplication. It is important to ensure, that the protocol facets do not @@ -229,7 +271,7 @@ namespace senf { \doc init_client init_server */ - template + template class ConcreteSocketProtocol : public virtual SocketProtocol { @@ -253,12 +295,23 @@ namespace senf { /////////////////////////////////////////////////////////////////////////// Policy const & policy() const; - + protected: + ClientSocketHandle clientHandle() const; + ///< Get client handle for associated socket + /**< Returns a client handle for the socket associated with + this protocol instance */ + ServerSocketHandle serverHandle() const; + ///< Get server handle for associated socket + /**< Returns a server handle for the socket associated with + this protocol instance */ private: - Policy policy_; + virtual std::auto_ptr clone(bool isServer) const; + virtual std::auto_ptr clone(int fd, bool isServer) const; + virtual SocketBody & body() const; + Policy policy_; }; /// @} @@ -277,4 +330,6 @@ namespace senf { // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" +// compile-command: "scons -u test" +// comment-column: 40 // End: