libcore/Relay.h

   1 //
   2 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010,
   3 //   2011 Free Software Foundation, Inc
   4 //
   5 // This program is free software; you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation; either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // This program is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with this program; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19 #ifndef GNASH_RELAY_H
  20 #define GNASH_RELAY_H
  21
  22 #include <boost/noncopyable.hpp>
  23
  24 namespace gnash {
  25     class as_object;
  26 }
  27
  28 namespace gnash {
  29
  30 /// This is the base class for type-specific object data.
  31 //
  32 /// A Relay is a polymorphic object that contains arbitrary native
  33 /// type information. Native functions may access the Relay object, determine
  34 /// its derived type, and change its state.
  35 //
  36 /// The base class does nothing. It provides a virtual function to mark
  37 /// GC resources if necessary in subclasses.
  38 //
  39 /// The simplest native types, such as Boolean or String, inherit from this
  40 /// base class directly. They have no GC resources and simply store a
  41 /// C++ type such as a boolean, double, or std::string, which native functions
  42 /// can access and manipulate.
  43 //
  44 /// More complex types may derive from a subclass of Relay that provides
  45 /// specific functionality such as updates from the VM.
  46 //
  47 /// An as_object with a non-null _relay member is a native class, as this
  48 /// information cannot be accessed by normal ActionScript functions.
  49 class Relay : boost::noncopyable
  50 {
  51 public:
  52     virtual ~Relay() = 0;
  53
  54     /// A Relay itself is not a GC object, but may point to GC resources.
  55     virtual void setReachable() {}
  56
  57     /// Handle any cleanup necessary before the Relay is destroyed.
  58     //
  59     /// Only the replacement of one Relay by another should cause this
  60     /// to happen. The cleanup may involve deregistration.
  61     virtual void clean() {}
  62 };
  63
  64 inline Relay::~Relay()
  65 {
  66 }
  67
  68 /// A native type that requires periodic updates from the core (movie_root).
  69 //
  70 /// Objects with this type of relay can be registered with movie_root, and
  71 /// recieve a callback on every advance.
  72 //
  73 /// This type of Relay holds a reference to its parent as_object (owner).
  74 /// If a reference to this ActiveRelay is held by another object,
  75 /// it must be marked reachable so that its owner is not deleted by the GC.
  76 //
  77 /// The function setReachable() is called on every GC run. It calls
  78 /// markReachableResources() and marks its owner.
  79 class ActiveRelay : public Relay
  80 {
  81 public:
  82
  83     explicit ActiveRelay(as_object* owner)
  84         :
  85         _owner(owner)
  86     {}
  87
  88     /// Make sure we are removed from the list of callbacks on destruction.
  89     virtual ~ActiveRelay();
  90
  91     /// ActiveRelay objects must have an advanceState method.
  92     virtual void update() = 0;
  93
  94     /// Mark any other reachable resources, and finally mark our owner
  95     //
  96     /// Do not override this function.
  97     virtual void setReachable();
  98
  99     /// Remove the ActiveRelay from movie_root's callback set.
 100     //
 101     /// This must be called before the Relay is destroyed!
 102     virtual void clean();
 103
 104     /// Return the as_object that this Relay is attached to.
 105     as_object& owner() const {
 106         return *_owner;
 107     }
 108
 109 protected:
 110
 111     /// Mark any reachable resources other than the owner.
 112     //
 113     /// Override this function if the subclass holds references to GC
 114     /// resources other than the owner.
 115     virtual void markReachableResources() const {}
 116
 117 private:
 118
 119     /// The as_object that owns this Relay.
 120     //
 121     /// Because we are deleted on destruction of the owner, this pointer will
 122     /// never be invalid as long as 'this' is valid.
 123     as_object* _owner;
 124
 125 };
 126
 127 } // namespace gnash
 128
 129 #endif