2 smobs.hh -- declare smob related stuff.
4 source file of the GNU LilyPond music typesetter
6 (c) 1999--2004 Han-Wen Nienhuys <hanwen@cs.uu.nl>
13 #include "lily-guile.hh"
18 Each smobbed C-object may only be interfaced by a single, unique
19 smob cell. Therefore NEVER provide a public function that will
20 create a smobcell for an existing object pointer.
22 There are two ways to reach this goal:
26 - Data structures that are encapsulated by GUILE. If constructed
27 through GUILE, you may only store them as protected SCMs, and may
28 not copy the pointer the object itself. Typical interface
32 SCM make_copy_scm () const {
33 Ssmob *sp = new Ssmob (*this);
34 return sp->smobbed_self ();
43 static SCM make_scm (void initdata) {
44 Ssmob * sp = new Ssmob (initdata);
45 return sp->smobbed_self ();
51 Objets of type Ssmob may live on the stack, or on the heap, or as
52 part of other objects. However, as soon as the object is smobbed,
53 by definition (by definition of the constructors, in this example),
54 lives on the heap as a separate object
56 - complex smobs: data structures whose identity is referenced and
57 stored both in C++ and in GUILE form. From going from C++ to GUILE,
58 you use smob_ptr->self_scm_
62 Csmob () { smobify_self (); }
63 Csmob (Csmob const & s) {
64 // don't copy self_scm_
69 A complex smob is a C++ class with static member functions to glue
70 it with Scheme. Every instance carries SELF_SCM_, a pointer to the
71 unique Scheme smob cell of itself.
73 Upon creation, SELF_SCM_ is protected, so if you choose to store it
74 in C++ structures, you need to do
78 ~Bla () { scm_gc_unprotect_object (ptr->self_scm_); }
82 If protection is done via GUILE, don't forget to unprotect AFTER putting
83 stuff into the GUILE datastructs
86 guile_data = gh_cons (ptr->self_scm_, guile_data);
89 Since GUILE takes care of the freeing the object, the destructor
92 DUMMY a thing to make sure compiles only work if this header
93 if this file is there.
98 smobify_self () might trigger a GC, so make sure that objects are
99 sane when you do smobify_self ().
102 #define DECLARE_SIMPLE_SMOBS(CL,dummy) \
104 SCM smobbed_copy () const; \
105 DECLARE_BASE_SMOBS(CL)
108 #define DECLARE_BASE_SMOBS(CL) \
109 friend class Non_existant_class ; \
111 static scm_t_bits smob_tag_; \
112 static SCM mark_smob (SCM); \
113 static size_t free_smob (SCM s); \
114 static int print_smob (SCM s, SCM p, scm_print_state*); \
116 static SCM equal_p (SCM a, SCM b);\
117 static CL * unsmob (SCM s){\
118 if (SCM_NIMP (s) && SCM_CELL_TYPE (s) == smob_tag_) \
119 return (CL*) SCM_CELL_WORD_1 (s); \
123 static SCM smob_p (SCM);\
124 static void init_smobs (); \
128 #define DECLARE_SMOBS(CL,dummy) \
129 DECLARE_BASE_SMOBS (CL) \
132 SCM unprotected_smobify_self ();\
134 SCM smobify_self (); \
137 SCM self_scm () const { return self_scm_; } \
140 #define DECLARE_UNSMOB(CL,name) \
142 unsmob_ ## name (SCM s) \
144 return CL::unsmob (s); \
149 #endif /* SMOBS_HH */