2 smobs.hh -- declare smob related stuff.
4 source file of the GNU LilyPond music typesetter
6 (c) 1999--2000 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_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 friend class Non_existant_class ; \
105 SCM smobbed_self () const; \
107 static long smob_tag_; \
108 static SCM mark_smob (SCM); \
109 static scm_sizet free_smob (SCM s); \
110 static int print_smob (SCM s, SCM p, scm_print_state*); \
112 static SCM equal_p (SCM a, SCM b);\
113 static CL * unsmob (SCM);\
114 static void init_smobs(); \
118 #define DECLARE_SMOBS(CL,dummy) \
119 DECLARE_SIMPLE_SMOBS(CL,dammy) \
122 SCM unprotected_smobify_self ();\
124 SCM smobify_self (); \
127 SCM self_scm () const { return self_scm_; } \
131 #endif /* SMOBS_HH */