X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=lily%2Finclude%2Fsmobs.hh;h=cd111981bbea9c0fa38f27032e1a9dfefd20eeac;hb=7dd2533deb5dbbab91600edca6624325bccb74cd;hp=a038db298e7ddf004b62358c01e85e9534bc8811;hpb=3a0e9efb7f067e5b334ba0596b95e15d96d7cc49;p=lilypond.git diff --git a/lily/include/smobs.hh b/lily/include/smobs.hh index a038db298e..cd111981bb 100644 --- a/lily/include/smobs.hh +++ b/lily/include/smobs.hh @@ -1,50 +1,208 @@ -/* - smobs.hh -- declare smob related stuff. - - source file of the GNU LilyPond music typesetter - - (c) 1999 Han-Wen Nienhuys - - */ +/* + This file is part of LilyPond, the GNU music typesetter. + + Copyright (C) 1999--2012 Han-Wen Nienhuys + + 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 . +*/ #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. + + + 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..> + } -/** - 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. + 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. - 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. + Complex_smob *p = new Complex_smob; + list = scm_cons (p->self_scm (), list); + p->unprotect (); - This is discouraged, though, because it causes memory leaks, and has - weird semantics. - + 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_SMOBS \ - SCM smobify_self (); \ - static SCM mark_smob (SCM); \ - static scm_sizet free_smob (SCM s); \ - static int print_smob (SCM s, SCM p, scm_print_state*); \ - static long smob_tag_; \ - static void init_smobs(); \ - void unsmobify_self ();\ - void do_smobify_self();\ - SCM self_scm_; - - -/** - 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_) - -/// Cast S. No checks are done. -#define SMOB_TO_TYPE(TYPE, S) ((TYPE*) SCM_CDR((S))) +#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 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 */