lily/include/smobs.hh

   1 /*
   2   This file is part of LilyPond, the GNU music typesetter.
   3
   4   Copyright (C) 1999--2012 Han-Wen Nienhuys <hanwen@xs4all.nl>
   5
   6   LilyPond is free software: you can redistribute it and/or modify
   7   it under the terms of the GNU General Public License as published by
   8   the Free Software Foundation, either version 3 of the License, or
   9   (at your option) any later version.
  10
  11   LilyPond is distributed in the hope that it will be useful,
  12   but WITHOUT ANY WARRANTY; without even the implied warranty of
  13   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14   GNU General Public License for more details.
  15
  16   You should have received a copy of the GNU General Public License
  17   along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef SMOBS_HH
  21 #define SMOBS_HH
  22
  23 #include "lily-guile.hh"
  24 #include "warn.hh"
  25
  26 /*
  27   Smobs are GUILEs mechanism of exporting C(++) objects to the Scheme
  28   world.  They are documented in the GUILE manual.
  29
  30
  31   In LilyPond, smobs are created from C++ objects through macros.
  32   There are two types of smob objects.
  33
  34   1. Simple smobs are intended for simple objects like numbers:
  35   immutable objects that can be copied without change of meaning.
  36
  37   To obtain an SCM version of a simple smob, use the member function
  38   SCM smobbed_copy ().
  39
  40   Simple smobs are created by adding the
  41   DECLARE_SIMPLE_SMOBS(Classname) to the declaration
  42
  43   2. Complex smobs are objects that have an identity. These objects
  44   carry this identity in the form of a self_scm () method, which is a
  45   SCM pointer to the object itself.
  46
  47   The constructor for a complex smob should have 3 steps:
  48
  49   * initialize all SCM members to an immediate value (like SCM_EOL)
  50
  51   * call smobify_self ()
  52
  53   * initialize SCM members
  54
  55   For example,
  56
  57   Complex_smob::Complex_smob () {
  58   scm_member_ = SCM_EOL;
  59   smobify_self ();
  60   scm_member_ = <..what you want to store..>
  61   }
  62
  63   after construction, the self_scm () field of a complex smob is
  64   protected from Garbage Collection.  This protection should be
  65   removed once the object is put into another (reachable) Scheme data
  66   structure, i.e.
  67
  68   Complex_smob *p = new Complex_smob;
  69   list = scm_cons (p->self_scm (), list);
  70   p->unprotect ();
  71
  72   Since unprotect returns the SCM object itself, this particular case
  73   can be written as
  74
  75   Complex_smob *p = new Complex_smob;
  76   list = scm_cons (p->unprotect (), list);
  77
  78   Complex smobs are made with DECLARE_SMOBS (Classname) in the class
  79   declaration.
  80
  81   CALLING INTERFACE
  82
  83   Common public methods to C++ smob objects:
  84
  85   unsmob (SCM x)  - unpacks X and returns pointer to the C++ object, or 0
  86   if it has the wrong type.
  87
  88   SCM equal_p (SCM a, SCM b) - compare A and B. Returns a Scheme boolean
  89
  90
  91   IMPLEMENTATION
  92
  93   For implementating a class, the following should be provided
  94
  95   - an equal_p () function (a default is in the
  96   IMPLEMENT_DEFAULT_EQUAL_P macro in ly-smobs.icc)
  97
  98   - mark_smob () function, that calls scm_gc_mark () on all Scheme
  99   objects in the class
 100
 101   - a print_smob () function, that displays a representation for
 102   debugging purposes
 103
 104   - A call to one of the IMPLEMENT_SMOBS or IMPLEMENT_SIMPLE_SMOBS macros
 105   from file "ly-smobs.icc"
 106 */
 107
 108 #define DECLARE_SIMPLE_SMOBS(CL)                \
 109   public:                                       \
 110   SCM smobbed_copy () const;                    \
 111   DECLARE_BASE_SMOBS (CL)
 112
 113 #define DECLARE_BASE_SMOBS(CL)                                  \
 114   friend class Non_existent_class;                              \
 115   private:                                                      \
 116   static const char* smob_name_; \
 117   static scm_t_bits smob_tag_;                                  \
 118   static SCM mark_smob (SCM);                                   \
 119   static size_t free_smob (SCM s);                              \
 120   static int print_smob (SCM s, SCM p, scm_print_state*);       \
 121   public:                                                       \
 122   static SCM equal_p (SCM a, SCM b);                            \
 123   static CL *unsmob (SCM s) __attribute__((pure))               \
 124   {                                                             \
 125     if (SCM_NIMP (s) && SCM_CELL_TYPE (s) == smob_tag_)         \
 126       return (CL *) SCM_CELL_WORD_1 (s);                        \
 127     else                                                        \
 128       return 0;                                                 \
 129   }                                                             \
 130   static SCM smob_p (SCM);                                      \
 131   static void init_smobs ();                                    \
 132   private:
 133
 134 #define DECLARE_SMOBS(CL)                       \
 135   DECLARE_BASE_SMOBS (CL)                       \
 136     protected:                                  \
 137   virtual ~CL ();                               \
 138   SCM unprotected_smobify_self ();              \
 139   private:                                      \
 140   void smobify_self ();                         \
 141   SCM self_scm_;                                \
 142   SCM protection_cons_;                         \
 143   public:                                       \
 144   SCM unprotect ();                             \
 145   void protect ();                              \
 146   SCM self_scm () const { return self_scm_; }   \
 147   private:
 148
 149 #define DECLARE_UNSMOB(CL, name)                \
 150   inline CL *                                   \
 151   unsmob_ ## name (SCM s)                       \
 152   {                                             \
 153     return CL::unsmob (s);                      \
 154   }
 155
 156 #define DECLARE_TYPE_P(CL) extern SCM CL ## _type_p_proc
 157
 158 void protect_smob (SCM smob, SCM *prot_cons);
 159 void unprotect_smob (SCM smob, SCM *prot_cons);
 160
 161 extern bool parsed_objects_should_be_dead;
 162 class parsed_dead
 163 {
 164   static vector<parsed_dead *> elements;
 165   SCM data;
 166   SCM readout_one ()
 167   {
 168     SCM res = data;
 169     data = SCM_UNDEFINED;
 170     return res;
 171   }
 172 public:
 173   parsed_dead () : data (SCM_UNDEFINED)
 174   {
 175     elements.push_back (this);
 176   }
 177   void checkin (SCM arg) { data = arg; }
 178   static SCM readout ();
 179 };
 180
 181 #ifndef NDEBUG
 182 #define ASSERT_LIVE_IS_ALLOWED(arg)                                     \
 183   do {                                                                  \
 184     static parsed_dead pass_here;                                       \
 185     if (parsed_objects_should_be_dead)                                  \
 186       pass_here.checkin (arg);                                          \
 187   } while (0)
 188 #else
 189 #define ASSERT_LIVE_IS_ALLOWED(arg) do { } \
 190   while (0)
 191 #endif
 192
 193 #endif /* SMOBS_HH */
 194