Line data    Source code

       1             : 
       2             : /* Copyright (c) 2009-2014, Stefan Eilemann <eile@equalizergraphics.com>
       3             :  *                    2010, Daniel Nachbaur <danielnachbaur@gmail.com>
       4             :  *
       5             :  * This file is part of Collage <https://github.com/Eyescale/Collage>
       6             :  *
       7             :  * This library is free software; you can redistribute it and/or modify it under
       8             :  * the terms of the GNU Lesser General Public License version 2.1 as published
       9             :  * by the Free Software Foundation.
      10             :  *
      11             :  * This library is distributed in the hope that it will be useful, but WITHOUT
      12             :  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
      13             :  * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
      14             :  * details.
      15             :  *
      16             :  * You should have received a copy of the GNU Lesser General Public License
      17             :  * along with this library; if not, write to the Free Software Foundation, Inc.,
      18             :  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
      19             :  */
      20             : 
      21             : #ifndef CO_SERIALIZABLE_H
      22             : #define CO_SERIALIZABLE_H
      23             : 
      24             : #include <co/object.h>        // base class
      25             : 
      26             : namespace co
      27             : {
      28             : namespace detail { class Serializable; }
      29             : 
      30             : /**
      31             :  * Base class for distributed, inheritable objects.
      32             :  *
      33             :  * This class implements one usage pattern of Object, which allows subclassing
      34             :  * and serialization of distributed Objects. The implementation hierarchy
      35             :  * Serializable -> eq::fabric::Object -> eq::fabric::Frustum illustrates the
      36             :  * usage of this class.
      37             :  */
      38             : class Serializable : public Object
      39             : {
      40             : public:
      41             :     /** @return the current dirty bit mask. @version 1.0 */
      42             :     CO_API uint64_t getDirty() const;
      43             : 
      44             :     /** @return true if the serializable has to be committed. @version 1.0 */
      45             :     CO_API bool isDirty() const override;
      46             : 
      47             :     /** @return true if the given dirty bits are set. @version 1.0 */
      48             :     CO_API virtual bool isDirty( const uint64_t dirtyBits ) const;
      49             : 
      50             :     /** @sa Object::commit() */
      51             :     CO_API uint128_t commit( const uint32_t incarnation = CO_COMMIT_NEXT )
      52             :         override;
      53             : 
      54             : protected:
      55             :     /** Construct a new Serializable. @version 1.0 */
      56             :     CO_API Serializable();
      57             : 
      58             :     /**
      59             :      * Construct an unmapped, unregistered copy of a serializable.
      60             :      * @version 1.0
      61             :      */
      62             :     CO_API Serializable( const Serializable& );
      63             : 
      64             :     /** Destruct the serializable. @version 1.0 */
      65             :     CO_API virtual ~Serializable();
      66             : 
      67             :     /** NOP assignment operator. @version 1.1.1 */
      68             :     Serializable& operator = ( const Serializable& from )
      69             :         { Object::operator = ( from ); return *this; }
      70             : 
      71             :     /**
      72             :      * Worker for pack() and getInstanceData().
      73             :      *
      74             :      * Override this and deserialize() to distribute subclassed data.
      75             :      *
      76             :      * This method is called with DIRTY_ALL from getInstanceData() and with
      77             :      * the actual dirty bits from pack(), which also resets the dirty state
      78             :      * afterwards. The dirty bits are transmitted beforehand, and do not
      79             :      * need to be transmitted by the overriding method.
      80             :      * @version 1.0
      81             :      */
      82           7 :     virtual void serialize( co::DataOStream&, const uint64_t ){}
      83             : 
      84             :     /**
      85             :      * Worker for unpack() and applyInstanceData().
      86             :      *
      87             :      * This function is called with the dirty bits send by the master
      88             :      * instance. The dirty bits are received beforehand, and do not need to
      89             :      * be deserialized by the overriding method.
      90             :      *
      91             :      * @sa serialize()
      92             :      * @version 1.0
      93             :      */
      94           4 :     virtual void deserialize( co::DataIStream&, const uint64_t ){}
      95             : 
      96             :     /**
      97             :      * The changed parts of the serializable since the last pack().
      98             :      *
      99             :      * Subclasses should define their own bits, starting at DIRTY_CUSTOM.
     100             :      * @version 1.0
     101             :      */
     102             :     enum DirtyBits
     103             :     {
     104             :         DIRTY_NONE       = 0,
     105             :         DIRTY_CUSTOM     = 1,
     106             :         DIRTY_ALL        = 0xFFFFFFFFFFFFFFFFull
     107             :     };
     108             : 
     109             :     /** Add dirty flags to mark data for distribution. @version 1.0 */
     110             :     CO_API virtual void setDirty( const uint64_t bits );
     111             : 
     112             :     /** Remove dirty flags to clear data from distribution. @version 1.0 */
     113             :     CO_API virtual void unsetDirty( const uint64_t bits );
     114             : 
     115             :     /** @sa Object::getChangeType() */
     116           0 :     ChangeType getChangeType() const override { return DELTA; }
     117             : 
     118             :     /** @sa Object::notifyAttached() */
     119             :     CO_API void notifyAttached() override;
     120             : 
     121           4 :     void getInstanceData( co::DataOStream& os ) final
     122           4 :         { serialize( os, DIRTY_ALL ); }
     123             : 
     124             :     CO_API void applyInstanceData( co::DataIStream& is ) final;
     125             : 
     126             :     CO_API void pack( co::DataOStream& os ) final;
     127             :     CO_API void unpack( co::DataIStream& is ) final;
     128             : 
     129             : private:
     130             :     detail::Serializable* const _impl;
     131             :     friend class detail::Serializable;
     132             : };
     133             : }
     134             : #endif // CO_SERIALIZABLE_H