FileHandle.ih

Go to the documentation of this file.

//
// Copyright (c) 2020 Fraunhofer Institute for Applied Information Technology (FIT)
//                    Network Research Group (NET)
//                    Schloss Birlinghoven, 53754 Sankt Augustin, GERMANY
//                    Contact: support@wiback.org
//
// This file is part of the SENF code tree.
// It is licensed under the 3-clause BSD License (aka New BSD License).
// See LICENSE.txt in the top level directory for details or visit
// https://opensource.org/licenses/BSD-3-Clause
//


/** \file
    \brief FileHandle internal header
 */

#ifndef IH_SENF_Socket_FileHandle_
#define IH_SENF_Socket_FileHandle_ 1

// Custom includes
#include <boost/intrusive_ptr.hpp>
#include <senf/Utils/intrusive_refcount.hh>
#include <senf/Utils/pool_alloc_mixin.hh>

//-/////////////////////////////////////////////////////////////////////////////////////////////////

namespace senf {

    class FileHandle;

    /** \brief FileHandle referenced body

        \internal

        The senf::FileBody class forms the body part of the handle/body structure of the FileHandle
        interface. It manages the FileHandle data and is referenced by senf::FileHandle. It is
        automatically managed using reference counting.

        Since the senf::FileHandle class forwards most calls directly to the underlying
        senf::FileBody instance, most members are documented in senf::FileHandle.

        \section filebody_new Writing senf::FileBody derived classes

        It is possible to write customized senf::FileBody derived body implementations. This
        implementation can then be used be a senf::FileHandle derived class to customize the
        FileHandle behavior. Handling the body directly by the handle class ensures, that no invalid
        handles can be created (a senf::FileHandle derived handle expecting a specific body type but
        pointing to a different body type).

        To customize the behavior, a virtual interface is provided. This interface only covers some
        basic functionality which is only used infrequently during the lifetime of a FileHandle
        instance.

        \attention Whenever a new class is derived from FileBody which adds new members, this class
            \e must also derive from senf::pool_alloc_mixin
      */
    class FileBody
        : public senf::intrusive_refcount,
          public senf::pool_alloc_mixin<FileBody>
    {
    public:
        //-/////////////////////////////////////////////////////////////////////////////////////////
        // Types

        typedef boost::intrusive_ptr<FileBody> ptr;

        //-/////////////////////////////////////////////////////////////////////////////////////////
        ///\name Structors and default members
        //\{

        explicit FileBody(int fd=-1);   ///< Create new instance
                                        /**< You need to pass a real file descriptor to this
                                           constructor not some arbitrary id even if you overload
                                           all the virtual members. If the file descriptor is -1 the
                                           resulting body/handle is not valid() */
        virtual ~FileBody();

        // NO DESTRUCTOR HERE (that is, only an empty virtual destructor) - destructors and virtual
        // functions don't mix. What would be in the the destructor is in 'destroyClose()' which is
        // called from FileHandle::~FileHandle() *before* the last handle dies.

        // no copy
        // no conversion constructors

        //\}
        //-/////////////////////////////////////////////////////////////////////////////////////////

        FileHandle handle();

        int fd() const;
        void fd(int fd);

        void * extraPtr() const;
        void extraPtr(void * ptr);

        void close();
        void terminate();
        void destroyClose();

        bool readable() const;
        bool waitReadable(senf::ClockService::clock_type timeout) const;
        bool writeable() const;
        bool waitWriteable(senf::ClockService::clock_type timeout) const;
        bool oobReadable() const;
        bool waitOOBReadable(senf::ClockService::clock_type timeout) const;

        bool blocking() const;
        void blocking(bool status);

        bool eof() const;
        bool valid() const;

    private:
        //-/////////////////////////////////////////////////////////////////////////////////////////
        // Virtual interface for subclasses to override

        virtual void v_close();         ///< Called to close the file descriptor
                                        /**< You should probably always call the global ::close()
                                           function in this member, however you might want to do
                                           some additional cleanup here. If the operation fails, you
                                           are allowed to throw (preferably a
                                           senf::SystemException).

                                        \throws senf::SystemException */
        virtual void v_terminate();     ///< Called to forcibly close the file descriptor
                                        /**< This member is called by the destructor (and by
                                           terminate()) to close the descriptor. This member must \e
                                           never throw, it should probably just ignore error
                                           conditions (there's not much else you can do) */
        virtual bool v_eof() const;     ///< Called by eof()
        virtual bool v_valid() const;   ///< Called by valid()
                                        /**< This member is only called, if the file descriptor is
                                           not -1 */

    protected:

    private:
        bool pollCheck(int fd, bool incoming, int timeout, bool oob=false) const;

        int fd_;
        void * extraPtr_;
    };

}

//-/////////////////////////////////////////////////////////////////////////////////////////////////
#endif


// Local Variables:
// mode: c++
// fill-column: 100
// c-file-style: "senf"
// indent-tabs-mode: nil
// ispell-local-dictionary: "american"
// compile-command: "scons -u test"
// comment-column: 40
// End: