X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=lily%2Finclude%2Fsmobs.hh;h=3c760cf33969953db4d8a31b7a3ca9c9a2c8cf2e;hb=5b4b0d6e9a197e8f9eb085b7c2ad78b8be3e5cfc;hp=2a519c4326596b9e4a3a457bcfff7668a252dcf8;hpb=94189ec2b8da6d7e89dc619c646a927adead9b19;p=lilypond.git diff --git a/lily/include/smobs.hh b/lily/include/smobs.hh index 2a519c4326..3c760cf339 100644 --- a/lily/include/smobs.hh +++ b/lily/include/smobs.hh @@ -1,133 +1,158 @@ -/* +/* smobs.hh -- declare smob related stuff. - + source file of the GNU LilyPond music typesetter - - (c) 1999--2001 Han-Wen Nienhuys - - */ + + (c) 1999--2008 Han-Wen Nienhuys +*/ #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_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 long smob_tag_; \ - static SCM mark_smob (SCM); \ - static scm_sizet 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 + + 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_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; + +#ifndef NDEBUG +#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;\ + } +#else +#define ASSERT_LIVE_IS_ALLOWED() +#endif #endif /* SMOBS_HH */