From: David Kastrup <dak@gnu.org>
Date: Tue, 9 Apr 2013 07:51:01 +0000 (+0200)
Subject: Add an explanatory comment regarding session-handling to scm/lily.scm
X-Git-Tag: release/2.17.16-1~7
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=86dfbf857b9e4afb3c431fd4b945a7baf6bc4cbb;p=lilypond.git

Add an explanatory comment regarding session-handling to scm/lily.scm
---

diff --git a/scm/lily.scm b/scm/lily.scm
index 3d179dd2cb..496598bbbc 100644
--- a/scm/lily.scm
+++ b/scm/lily.scm
@@ -43,6 +43,30 @@
    (string-downcase
     (car (string-tokenize (utsname:sysname (uname)))))))
 
+;;
+;; Session-handling variables and procedures.
+;;
+;;  A "session" corresponds to one .ly file processed on a LilyPond
+;;  command line.  Every session gets to see a reasonably fresh state
+;;  of LilyPond and should work independently from previous files.
+;;
+;;  Session management relies on cooperation, namely the user not
+;;  trying to change variables and data structures internal to
+;;  LilyPond.  It is not proof against in-place modification of data
+;;  structures (as they are just reinitialized with the original
+;;  identities), and it is not proof against tampering with internals.
+;;
+;;  As a consequence, session management is not sufficient for
+;;  separating multiple independent .ly files in "-dsafe" mode: you
+;;  should give each its own LilyPond process when reliable separation
+;;  is mandatory.
+;;
+;;  For standard tasks and programming practices, multiple sessions in
+;;  the same LilyPond job should work reasonably independently and
+;;  without "bleed-over" while still loading and compiling the
+;;  relevant .scm and .ly files only once.
+;;
+
 (define lilypond-declarations '())
 (define after-session-hook (make-hook))