X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=lily%2Finclude%2Fsmobs.hh;h=a816b67ca3df9e0f0f2228e5729102c06d0e0036;hb=47db9a3883d726ca53e2133a3b2298f78dd6a32e;hp=61b8ae37fd2e64fc3e0f3f0c7111f0910738131b;hpb=ee4bc843ba15ebbedd8578cbb8e5e477925c413f;p=lilypond.git diff --git a/lily/include/smobs.hh b/lily/include/smobs.hh index 61b8ae37fd..a816b67ca3 100644 --- a/lily/include/smobs.hh +++ b/lily/include/smobs.hh @@ -1,9 +1,20 @@ /* - smobs.hh -- declare smob related stuff. + This file is part of LilyPond, the GNU music typesetter. - source file of the GNU LilyPond music typesetter + Copyright (C) 1999--2015 Han-Wen Nienhuys - (c) 1999--2007 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 @@ -11,13 +22,17 @@ #include "lily-guile.hh" #include "warn.hh" +#include /* 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. + In LilyPond, C++ objects can be placed under the control of GUILE's + type system and garbage collection mechanism by inheriting from one + of several Smob base classes. + There are two types of smob objects. 1. Simple smobs are intended for simple objects like numbers: @@ -26,16 +41,29 @@ 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 + Simple smobs are created by deriving from Simple_smob. + + 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. + 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 a non-immediate value (like SCM_EOL) + * initialize all SCM members to an immediate value (like SCM_EOL) * call smobify_self () @@ -43,7 +71,7 @@ For example, - Complex_smob::Complex_smob () { + Complex_smob::Complex_smob : public Smob () { scm_member_ = SCM_EOL; smobify_self (); scm_member_ = <..what you want to store..> @@ -56,103 +84,243 @@ Complex_smob *p = new Complex_smob; list = scm_cons (p->self_scm (), list); - scm_gc_unprotect_object (p->self_scm ()); + p->unprotect (); - Complex smobs are made with DECLARE_SMOBS (Classname) in the class - declaration. + Since unprotect returns the SCM object itself, this particular case + can be written as - CALLING INTERFACE + Complex_smob *p = new Complex_smob; + list = scm_cons (p->unprotect (), list); - Common public methods to C++ smob objects: + Complex smobs are created by deriving from Smob. - unsmob (SCM x) - unpacks X and returns pointer to the C++ object, or 0 - if it has the wrong type. + CALLING INTERFACE - SCM equal_p (SCM a, SCM b) - compare A and B. Returns a Scheme boolean + 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. This can be used as a boolean + condition at C++ level. + - smob_p (SCM x) returns #t or #f at Scheme level. IMPLEMENTATION - For implementating a class, the following should be provided + For implementating a class, the following public members can be + provided in the top class itself: - - an equal_p () function (a default is in the - IMPLEMENT_DEFAULT_EQUAL_P macro in ly-smobs.icc) + - SCM equal_p (SCM a, SCM b) - compare A and B. Returns a Scheme + boolean. If the class does not define this function, equal? will + be equivalent to eq?. The function will only be called when both + objects are of the respective type and not eq? to each other. - mark_smob () function, that calls scm_gc_mark () on all Scheme - objects in the class + objects in the class. If the class does not define this function, + it must not contain non-immediate Scheme values. - a print_smob () function, that displays a representation for - debugging purposes + debugging purposes. If the class does not define this function, + the output will be # when printing. + + - a static const type_p_name_[] string set to something like + "ly:grob?". When provided, an accordingly named function for + checking for the given smob type will be available in Scheme. - - 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) \ - { \ - 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); \ +// Initialization class. Create a variable or static data member of +// this type at global scope (or creation will happen too late for +// Scheme initialization), initialising with a function to be called. +// Reference somewhere (like in the constructor of the containing +// class) to make sure the variable is actually instantiated. + +class Scm_init { +public: + Scm_init () { } + Scm_init (void (*fun) (void)) + { + add_scm_init_func (fun); } - -#define DECLARE_TYPE_P(CL) extern SCM CL ## _type_p_proc +}; + +template +class Smob_base +{ + static scm_t_bits smob_tag_; + static Scm_init scm_init_; + static void init (void); + static string smob_name_; + static Super *unchecked_unsmob (SCM s) + { + return reinterpret_cast (SCM_SMOB_DATA (s)); + } +protected: + // reference scm_init_ in smob_tag which is sure to be called. The + // constructor, in contrast, may not be called at all in classes + // like Smob1. + static scm_t_bits smob_tag () { (void) scm_init_; return smob_tag_; } + Smob_base () { } + static SCM register_ptr (Super *p); + static Super *unregister_ptr (SCM obj); +private: + // Those fallbacks are _only_ for internal use by Smob_base. They + // are characterized by no knowledge about the implemented type + // apart from the type's name. Overriding them as a template + // specialization is _not_ intended since a type-dependent + // implementation will in general need access to possibly private + // parts of the Super class. So any class-dependent override should + // be done by redefining the respective function in the Super class + // (where it will mask the private template member) rather than + // specializing a different template function/pointer. + // + // Most default functions are do-nothings. void init() will + // recognize their address when not overriden and will then refrain + // altogether from passing the the respective callbacks to GUILE. + SCM mark_smob (void); + static SCM mark_trampoline (SCM); // Used for calling mark_smob + static size_t free_smob (SCM obj); + static SCM equal_p (SCM, SCM); + int print_smob (SCM, scm_print_state *); + static int print_trampoline (SCM, SCM, scm_print_state *); + + // type_p_name_ can be overriden in the Super class with a static + // const char [] string. This requires both a declaration in the + // class as well as a single instantiation outside. Using a + // template specialization for supplying a different string name + // right in Smob_base itself seems tempting, but the C++ + // rules would then require a specialization declaration at the + // class definition site as well as a specialization instantiation + // in a single compilation unit. That requires just as much source + // code maintenance while being harder to understand and quite + // trickier in its failure symptoms when things go wrong. So we + // just use a static zero as "not here" indication. + static const int type_p_name_ = 0; + + // LY_DECLARE_SMOB_PROC is used in the Super class definition for + // making a smob callable like a function. Declaration has to be + // public. It may be either be completed with a semicolon in which + // case a definition of the member function smob_proc has to be done + // outside of the class body, or the semicolon is left off and an + // inline function body is added immediately below. It would be + // nice if this were a non-static member function but it would seem + // tricky to do the required trampolining for unsmobbing the first + // argument of the callback and using it as a this pointer. +#define LY_DECLARE_SMOB_PROC(REQ, OPT, VAR, ARGLIST) \ + static const int smob_proc_signature_ = ((REQ)<<8)|((OPT)<<4)|(VAR); \ + static SCM smob_proc ARGLIST + + // a separate LY_DEFINE_SMOB_PROC seems sort of pointless as it + // would just result in SCM CLASS::smob_proc ARGLIST + // + // The default case without function functionality is recognized by + // smob_proc_signature being -1. + static const int smob_proc = 0; + static const int smob_proc_signature_ = -1; + +public: + static bool is_smob (SCM s) + { + return SCM_SMOB_PREDICATE (smob_tag (), s); + } + static SCM smob_p (SCM s) + { + return is_smob (s) ? SCM_BOOL_T : SCM_BOOL_F; + } + static Super *unsmob (SCM s) + { + return is_smob (s) ? Super::unchecked_unsmob (s) : 0; + } +}; + +// Simple smobs +template +class Simple_smob : public Smob_base { +public: + static size_t free_smob (SCM obj) + { + delete Smob_base::unregister_ptr (obj); + return 0; + } + SCM smobbed_copy () const + { + Super *p = new Super(*static_cast (this)); + return Smob_base::register_ptr (p); + } +}; void protect_smob (SCM smob, SCM *prot_cons); void unprotect_smob (SCM smob, SCM *prot_cons); -extern bool parsed_objects_should_be_dead; +template +class Smob : public Smob_base { +private: + SCM self_scm_; + SCM protection_cons_; + Smob (const Smob &); // Do not define! Not copyable! +protected: + Smob () : self_scm_ (SCM_UNDEFINED), protection_cons_ (SCM_EOL) { }; +public: + static size_t free_smob (SCM obj) + { + delete Smob_base::unregister_ptr (obj); + return 0; + } + SCM unprotected_smobify_self () + { + self_scm_ = Smob_base::register_ptr (static_cast (this)); + return self_scm_; + } + void protect () + { + protect_smob (self_scm_, &protection_cons_); + } + SCM unprotect () + { + unprotect_smob (self_scm_, &protection_cons_); + return self_scm_; + } + void smobify_self () { + self_scm_ = unprotected_smobify_self (); + protect (); + } + SCM self_scm () const { return self_scm_; } +}; -#ifndef NDEDUG -#define ASSERT_LIVE_IS_ALLOWED() \ - static bool passed_here_once;\ - if (parsed_objects_should_be_dead && !passed_here_once) { \ - ::programming_error (string ("Parsed object should be dead: ") + __PRETTY_FUNCTION__ ); \ - passed_here_once = true;\ - } +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 (); +}; + +// This does not appear to work with GUILEv2's garbage collector: +// Objects are found in the GC phase but printing them will crash at +// least some, so they are apparently not protected in spite of being +// included in the GC scans. So it would appear that scanning smobs +// is not equivalent to marking them. Ugh. +#if !defined(NDEBUG) && !GUILEV2 +#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() +#define ASSERT_LIVE_IS_ALLOWED(arg) do { (void)(arg); } \ + while (0) #endif +#include "smobs.tcc" #endif /* SMOBS_HH */ -