lily/include/smobs.hh

   1 /*
   2   smobs.hh -- declare smob related stuff.
   3
   4   source file of the GNU LilyPond music typesetter
   5
   6   (c) 1999--2007 Han-Wen Nienhuys <hanwen@xs4all.nl>
   7 */
   8
   9 #ifndef SMOBS_HH
  10 #define SMOBS_HH
  11
  12 #include "lily-guile.hh"
  13 #include "warn.hh"
  14
  15 /*
  16   Smobs are GUILEs mechanism of exporting C(++) objects to the Scheme
  17   world.  They are documented in the GUILE manual.
  18
  19
  20   In LilyPond, smobs are created from C++ objects through macros.
  21   There are two types of smob objects.
  22
  23   1. Simple smobs are intended for simple objects like numbers:
  24   immutable objects that can be copied without change of meaning.
  25
  26   To obtain an SCM version of a simple smob, use the member function
  27   SCM smobbed_copy ().
  28
  29   Simple smobs are created by adding the
  30   DECLARE_SIMPLE_SMOBS(Classname) to the declaration
  31
  32   2. Complex smobs are objects that have an identity. These objects
  33   carry this identity in the form of a self_scm () method, which is a
  34   SCM pointer to the object itself.
  35
  36   The constructor for a complex smob should have 3 steps:
  37
  38   * initialize all SCM members to a non-immediate value (like SCM_EOL)
  39
  40   * call smobify_self ()
  41
  42   * initialize SCM members
  43
  44   For example,
  45
  46   Complex_smob::Complex_smob () {
  47   scm_member_ = SCM_EOL;
  48   smobify_self ();
  49   scm_member_ = <..what you want to store..>
  50   }
  51
  52   after construction, the self_scm () field of a complex smob is
  53   protected from Garbage Collection.  This protection should be
  54   removed once the object is put into another (reachable) Scheme data
  55   structure, i.e.
  56
  57   Complex_smob *p = new Complex_smob;
  58   list = scm_cons (p->self_scm (), list);
  59   scm_gc_unprotect_object (p->self_scm ());
  60
  61   Complex smobs are made with DECLARE_SMOBS (Classname) in the class
  62   declaration.
  63
  64   CALLING INTERFACE
  65
  66   Common public methods to C++ smob objects:
  67
  68   unsmob (SCM x)  - unpacks X and returns pointer to the C++ object, or 0
  69   if it has the wrong type.
  70
  71   SCM equal_p (SCM a, SCM b) - compare A and B. Returns a Scheme boolean
  72
  73
  74   IMPLEMENTATION
  75
  76   For implementating a class, the following should be provided
  77
  78   - an equal_p () function (a default is in the
  79   IMPLEMENT_DEFAULT_EQUAL_P macro in ly-smobs.icc)
  80
  81   - mark_smob () function, that calls scm_gc_mark () on all Scheme
  82   objects in the class
  83
  84   - a print_smob () function, that displays a representation for
  85   debugging purposes
  86
  87   - A call to one of the IMPLEMENT_SMOBS or IMPLEMENT_SIMPLE_SMOBS macros
  88   from file "ly-smobs.icc"
  89 */
  90
  91 #define DECLARE_SIMPLE_SMOBS(CL)                \
  92   public:                                       \
  93   SCM smobbed_copy () const;                    \
  94   DECLARE_BASE_SMOBS (CL)
  95
  96 #define DECLARE_BASE_SMOBS(CL)                                  \
  97   friend class Non_existent_class;                              \
  98   private:                                                      \
  99   static const char* smob_name_; \
 100   static scm_t_bits smob_tag_;                                  \
 101   static SCM mark_smob (SCM);                                   \
 102   static size_t free_smob (SCM s);                              \
 103   static int print_smob (SCM s, SCM p, scm_print_state*);       \
 104   public:                                                       \
 105   static SCM equal_p (SCM a, SCM b);                            \
 106   static CL *unsmob (SCM s) __attribute__((pure))               \
 107   {                                                             \
 108     if (SCM_NIMP (s) && SCM_CELL_TYPE (s) == smob_tag_)         \
 109       return (CL *) SCM_CELL_WORD_1 (s);                        \
 110     else                                                        \
 111       return 0;                                                 \
 112   }                                                             \
 113   static SCM smob_p (SCM);                                      \
 114   static void init_smobs ();                                    \
 115   private:
 116
 117 #define DECLARE_SMOBS(CL)                       \
 118   DECLARE_BASE_SMOBS (CL)                       \
 119     protected:                                  \
 120   virtual ~CL ();                               \
 121   SCM unprotected_smobify_self ();              \
 122   private:                                      \
 123   void smobify_self ();                         \
 124   SCM self_scm_;                                \
 125   SCM protection_cons_;                         \
 126   public:                                       \
 127   SCM unprotect ();                             \
 128   void protect ();                              \
 129   SCM self_scm () const { return self_scm_; }   \
 130   private:
 131
 132 #define DECLARE_UNSMOB(CL, name)                \
 133   inline CL *                                   \
 134   unsmob_ ## name (SCM s)                       \
 135   {                                             \
 136     return CL::unsmob (s);                      \
 137   }
 138
 139 #define DECLARE_TYPE_P(CL) extern SCM CL ## _type_p_proc
 140
 141 void protect_smob (SCM smob, SCM *prot_cons);
 142 void unprotect_smob (SCM smob, SCM *prot_cons);
 143
 144 extern bool parsed_objects_should_be_dead;
 145
 146 #ifndef NDEBUG
 147 #define ASSERT_LIVE_IS_ALLOWED()     \
 148   static bool passed_here_once;\
 149   if (parsed_objects_should_be_dead && !passed_here_once) { \
 150     ::programming_error (string ("Parsed object should be dead: ")  + __PRETTY_FUNCTION__ ); \
 151     passed_here_once = true;\
 152   }
 153 #else
 154 #define ASSERT_LIVE_IS_ALLOWED()
 155 #endif
 156
 157 #endif /* SMOBS_HH */
 158