source file of the GNU LilyPond music typesetter
- (c) 1999 Han-Wen Nienhuys <hanwen@cs.uu.nl>
+ (c) 1999--2004 Han-Wen Nienhuys <hanwen@cs.uu.nl>
*/
#include "lily-guile.hh"
-/**
- A smob is a C++ class with static member functions to glue it with
- Scheme. Every instance carries SELF_SCM_, a pointer to the Scheme
- smob of itself. Upon destruction, SELF_SCM_ is set to SCM_EOL.
- smob_free() checks if SELF_SCM_ equals its argument, so we can also
- use a smobbified object on the stack: the destruction will happen
- before GC hits the object.
+/*
+ Smobs are GUILEs mechanism of exporting C(++) objects to the Scheme
+ world. They are documented in the GUILE manual.
- This is discouraged, though, because it causes memory leaks, and has
- weird semantics.
+
+ In LilyPond, smobs are created from C++ objects through macros.
+ There are two types of smob objects.
+
+ 1. Simple smobs are intended for simple objects like numbers:
+ immutable objects that can be copied without change of meaning.
+
+ To obtain an SCM version of a simple smob, use the member function
+ SCM smobbed_copy ().
+
+ Simple smobs are created by adding the
+ DECLARE_SIMPLE_SMOBS(Classname,) to the declaration
+
+ 2. Complex smobs are objects that have an identity. These objects
+ carry this identity in the form of a self_scm () method, which is a
+ SCM pointer to the object itself.
+
+ The constructor for a complex smob should have 3 steps:
+
+ * initialize all SCM members to a non-immediate value (like SCM_EOL)
+
+ * call smobify_self ()
+
+ * initialize SCM members
+
+ For example,
+
+ Complex_smob::Complex_smob () {
+ scm_member_ = SCM_EOL;
+ smobify_self ();
+ scm_member_ = <..what you want to store..>
+ }
+
+ after construction, the self_scm () field of a complex smob is
+ protected from Garbage Collection. This protection should be
+ removed once the object is put into another (reachable) Scheme data
+ structure, i.e.
+
+ Complex_smob *p = new Complex_smob;
+ list = scm_cons (p->self_scm (), list);
+ scm_gc_unprotect_object (p->self_scm ());
+
+ Complex smobs are made with DECLARE_SMOBS (Classname,) in the class
+ declaration.
+
+ CALLING INTERFACE
+ Common public methods to C++ smob objects:
+
+ unsmob (SCM x) - unpacks X and returns pointer to the C++ object, or 0
+ if it has the wrong type.
+
+ SCM equal_p (SCM a, SCM b) - compare A and B. Returns a Scheme boolean
+
+
+ IMPLEMENTATION
+
+ For implementating a class, the following should be provided
+
+ - an equal_p () function (a default is in the
+ IMPLEMENT_DEFAULT_EQUAL_P macro in ly-smobs.icc)
+ - mark_smob () function, that calls scm_gc_mark () on all Scheme
+ objects in the class
+
+ - a print_smob () function, that displays a representation for
+ debugging purposes
+
+ - A call to one of the IMPLEMENT_SMOBS or IMPLEMENT_SIMPLE_SMOBS macros
+ from file "ly-smobs.icc"
*/
-#define DECLARE_SMOBS \
- SCM smobify_self (); \
+#define DECLARE_SIMPLE_SMOBS(CL, dummy) \
+public: \
+ SCM smobbed_copy () const; \
+DECLARE_BASE_SMOBS(CL)
+
+
+#define DECLARE_BASE_SMOBS(CL) \
+ friend class Non_existent_class; \
+private: \
+ static scm_t_bits smob_tag_; \
static SCM mark_smob (SCM); \
- static scm_sizet free_smob (SCM s); \
+ static size_t free_smob (SCM s); \
static int print_smob (SCM s, SCM p, scm_print_state*); \
- static long smob_tag_; \
+public: \
static SCM equal_p (SCM a, SCM b);\
- static void init_smobs(); \
- void unsmobify_self ();\
- void do_smobify_self();\
- SCM self_scm_;
+ static CL * unsmob (SCM s){\
+ if (SCM_NIMP (s) && SCM_CELL_TYPE (s) == smob_tag_) \
+ return (CL*) SCM_CELL_WORD_1 (s); \
+ else \
+ return 0; \
+} \
+ static SCM smob_p (SCM);\
+ static void init_smobs (); \
+private:
-/**
- Check if S is of the specified C++ class.
- */
-#define SMOB_IS_TYPE_B(TYPE, S) (SCM_NIMP((S)) && SCM_CAR((S)) == TYPE::smob_tag_)
+#define DECLARE_SMOBS(CL,dummy) \
+ DECLARE_BASE_SMOBS (CL) \
+protected:\
+ virtual ~CL ();\
+ SCM unprotected_smobify_self ();\
+private: \
+ void smobify_self (); \
+ SCM self_scm_; \
+public: \
+ SCM self_scm () const { return self_scm_; } \
+private:
+
+#define DECLARE_UNSMOB(CL,name) \
+inline CL * \
+unsmob_ ## name (SCM s) \
+{ \
+return CL::unsmob (s); \
+}
+
+#define DECLARE_TYPE_P(CL) extern SCM CL ## _type_p_proc
-/// Cast S. No checks are done.
-#define SMOB_TO_TYPE(TYPE, S) ((TYPE*) SCM_CDR((S)))
#endif /* SMOBS_HH */
projects / lilypond.git / blobdiff