Merge remote-tracking branch 'origin/translation' into staging

[lilypond.git] / lily / include / smobs.hh

diff --git a/lily/include/smobs.hh b/lily/include/smobs.hh
index 22a4d183099bf069d70fe9cc423c851d180bd2cc..49c29325f0031f4e61908a1ee9035fa7f844cfc5 100644 (file)
--- a/lily/include/smobs.hh
+++ b/lily/include/smobs.hh
@@ -1,7 +1,7 @@
 /*
   This file is part of LilyPond, the GNU music typesetter.
 
-  Copyright (C) 1999--2012 Han-Wen Nienhuys <hanwen@xs4all.nl>
+  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
@@ -40,13 +40,27 @@
   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.
+  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 ()
 
@@ -67,7 +81,13 @@
 
   Complex_smob *p = new Complex_smob;
   list = scm_cons (p->self_scm (), list);
-  scm_gc_unprotect_object (p->self_scm ());
+  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.
@@ -153,10 +173,12 @@ 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 {
+class parsed_dead
+{
   static vector<parsed_dead *> elements;
   SCM data;
-  SCM readout_one () {
+  SCM readout_one ()
+  {
     SCM res = data;
     data = SCM_UNDEFINED;
     return res;
@@ -171,14 +193,14 @@ public:
 };
 
 #ifndef NDEBUG
-#define ASSERT_LIVE_IS_ALLOWED(arg)                                    \
-  do {                                                                 \
-    static parsed_dead pass_here;                                      \
-    if (parsed_objects_should_be_dead)                                 \
-      pass_here.checkin (arg);                                         \
+#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 { } \
+#define ASSERT_LIVE_IS_ALLOWED(arg) do { (void)(arg); }  \
   while (0)
 #endif