-/*
- smobs.hh -- declare smob related stuff.
-
- source file of the GNU LilyPond music typesetter
-
- (c) 1999--2001 Han-Wen Nienhuys <hanwen@cs.uu.nl>
-
- */
+/*
+ This file is part of LilyPond, the GNU music typesetter.
+
+ Copyright (C) 1999--2014 Han-Wen Nienhuys <hanwen@xs4all.nl>
+
+ LilyPond is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ LilyPond is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with LilyPond. If not, see <http://www.gnu.org/licenses/>.
+*/
#ifndef SMOBS_HH
#define SMOBS_HH
#include "lily-guile.hh"
-
+#include "warn.hh"
/*
+ Smobs are GUILEs mechanism of exporting C(++) objects to the Scheme
+ world. They are documented in the GUILE manual.
- Each smobbed C-object may only be interfaced by a single, unique
- smob cell. Therefore NEVER provide a public function that will
- create a smobcell for an existing object pointer.
-
- There are two ways to reach this goal:
-
- simple smobs:
-
- - Data structures that are encapsulated by GUILE. If constructed
- through GUILE, you may only store them as protected SCMs, and may
- not copy the pointer the object itself. Typical interface
-
- struct Ssmob {
- public:
- SCM make_copy_scm () const {
- Ssmob *sp = new Ssmob (*this);
- return sp->smobbed_self ();
- }
- };
-
- or
-
- struct Ssmob {
- public:
- DECLARE_SIMPLE_SMOBS;
- static SCM make_scm (void initdata) {
- Ssmob * sp = new Ssmob (initdata);
- return sp->smobbed_self ();
- }
- private:
- Ssmob (initdata);
- }
-
- Objets of type Ssmob may live on the stack, or on the heap, or as
- part of other objects. However, as soon as the object is smobbed,
- by definition (by definition of the constructors, in this example),
- lives on the heap as a separate object
-
- - complex smobs: data structures whose identity is referenced and
- stored both in C++ and in GUILE form. From going from C++ to GUILE,
- you use smob_ptr->self_scm_
-
- class Csmob {
- DECLARE_SMOBS;
- Csmob () { smobify_self (); }
- Csmob (Csmob const & s) {
- // don't copy self_scm_
- smobify_self ();
- }
- };
-
- A complex smob is a C++ class with static member functions to glue
- it with Scheme. Every instance carries SELF_SCM_, a pointer to the
- unique Scheme smob cell of itself.
-
- Upon creation, SELF_SCM_ is protected, so if you choose to store it
- in C++ structures, you need to do
-
- class Bla {
- Csmob *ptr;
- ~Bla () { scm_gc_unprotect_object (ptr->self_scm_); }
-
- };
-
- If protection is done via GUILE, don't forget to unprotect AFTER putting
- stuff into the GUILE datastructs
-
-
- guile_data = gh_cons (ptr->self_scm_, guile_data);
- ptr->self_scm_
-
- Since GUILE takes care of the freeing the object, the destructor
- is private.
-
- DUMMY a thing to make sure compiles only work if this header
- if this file is there.
-
-
- WARNING:
-
- smobify_self () might trigger a GC, so make sure that objects are
- sane when you do smobify_self ().
-*/
-#define DECLARE_SIMPLE_SMOBS(CL,dummy) \
-protected: \
- friend class Non_existant_class ; \
- SCM smobbed_self () const; \
-private:\
- static scm_t_bits smob_tag_; \
- static SCM mark_smob (SCM); \
- static size_t free_smob (SCM s); \
- static int print_smob (SCM s, SCM p, scm_print_state*); \
-public: \
- static SCM equal_p (SCM a, SCM b);\
- static CL * unsmob (SCM);\
- static SCM smob_p (SCM);\
- static void init_smobs (); \
-private:
-
-
-#define DECLARE_SMOBS(CL,dummy) \
- DECLARE_SIMPLE_SMOBS (CL,dammy) \
-protected:\
- virtual ~CL ();\
- SCM unprotected_smobify_self ();\
-private: \
- SCM smobify_self (); \
- SCM self_scm_; \
-public: \
- SCM self_scm () const { return self_scm_; } \
-private:
+ 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
+
+ A simple smob is only optionally under the reign of the GUILE
+ garbage collector: its usual life time is that of a normal C++
+ object. While a smobbed_copy () is fully under control of the
+ garbage collector and will have its mark_smob function called during
+ garbage collection, an automatic variable of this type will not have
+ mark_smob called, but rather have its memory image in the call stack
+ scanned for contained non-immediate SCM values. Anything requiring
+ more complex mark_smob behavior is not suitable for a simple smob.
+
+ When you create a smobbed_copy, the _copy_ is fully managed by the
+ GUILE memory system. As a corollary, multiple smobbed_copy calls
+ yield multiple GUILE objects generally not eq? to each other.
+
+ 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. Complex smobs are always under
+ control of the GUILE memory system.
+
+ The constructor for a complex smob should have 3 steps:
+
+ * initialize all SCM members to an 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);
+ p->unprotect ();
+
+ Since unprotect returns the SCM object itself, this particular case
+ can be written as
+
+ Complex_smob *p = new Complex_smob;
+ list = scm_cons (p->unprotect (), list);
+
+ 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_SIMPLE_SMOBS(CL) \
+ public: \
+ SCM smobbed_copy () const; \
+ DECLARE_BASE_SMOBS (CL)
+
+#define DECLARE_BASE_SMOBS(CL) \
+ friend class Non_existent_class; \
+ private: \
+ static const char* smob_name_; \
+ static scm_t_bits smob_tag_; \
+ static SCM mark_smob (SCM); \
+ static size_t free_smob (SCM s); \
+ static int print_smob (SCM s, SCM p, scm_print_state*); \
+ public: \
+ static SCM equal_p (SCM a, SCM b); \
+ static CL *unsmob (SCM s) __attribute__((pure)) \
+ { \
+ 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:
+
+#define DECLARE_SMOBS(CL) \
+ DECLARE_BASE_SMOBS (CL) \
+ protected: \
+ virtual ~CL (); \
+ SCM unprotected_smobify_self (); \
+ private: \
+ void smobify_self (); \
+ SCM self_scm_; \
+ SCM protection_cons_; \
+ public: \
+ SCM unprotect (); \
+ void protect (); \
+ 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
+
+void protect_smob (SCM smob, SCM *prot_cons);
+void unprotect_smob (SCM smob, SCM *prot_cons);
+
+extern bool parsed_objects_should_be_dead;
+class parsed_dead
+{
+ static vector<parsed_dead *> elements;
+ SCM data;
+ SCM readout_one ()
+ {
+ SCM res = data;
+ data = SCM_UNDEFINED;
+ return res;
+ }
+public:
+ parsed_dead () : data (SCM_UNDEFINED)
+ {
+ elements.push_back (this);
+ }
+ void checkin (SCM arg) { data = arg; }
+ static SCM readout ();
+};
+
+#ifndef NDEBUG
+#define ASSERT_LIVE_IS_ALLOWED(arg) \
+ do { \
+ static parsed_dead pass_here; \
+ if (parsed_objects_should_be_dead) \
+ pass_here.checkin (arg); \
+ } while (0)
+#else
+#define ASSERT_LIVE_IS_ALLOWED(arg) do { (void)(arg); } \
+ while (0)
+#endif
#endif /* SMOBS_HH */