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