+ When we introduced the polyphonic keyword + previously, we learned that a script may automatically be suspended by + the sampler at any time and then your script is thus sleeping for an + arbitrary while. The sampler must do such auto suspensions under certain + situations in cases where an instrument script may become a hazard for the + sampler's overall real-time stability. If the sampler would not do so, then + instrument scripts might easily cause audio dropouts, or at worst, buggy + instrument scripts might even lock up the entire sampler in an endless + loop. So auto suspension is an essential feature of the sampler's real-time + instrument script engine. +
++ Now the problem as a script author is that you don't really know beforehand + why and when your script might get auto suspended by the sampler. And when + you are working on more complex, sophisticated scripts, you will notice + that this might indeed be a big problem in certain sections of your scripts. + Because in practice, a sophisticated script often has at least one certain + consecutive portion of statements which must be executed in strict consecutive order + by the sampler, which might otherwise cause concurrency issues and thus + misbehavior of your script if that sensible code section was auto suspended + in between. A typical example of such concurrency sensible code sections are + statements which are reading and conditionally modifying global variables. + If your script gets auto suspended in such a code section, another + script handler instance might then interfere and change those global + variables in between. +
++ To avoid that, you can place such a sensible code section at the very beginning + of your event handler. For example consider you might be writing a custom + glissando + script starting like this: +
+
+on init
+ declare $keysDown
+ declare $firstNoteID
+ declare $firstNoteNr
+ declare $firstVelocity
+end on
+
+on note
+ { The concurrency sensible code section for the "first active" note. }
+ inc($keysDown)
+ if ($keysDown = 1 or event_status($firstNoteID) = $EVENT_STATUS_INACTIVE)
+ $firstNoteID = $EVENT_ID
+ $firstNoteNr = $EVENT_NOTE
+ $firstVelocity = $EVENT_VELOCITY
+ exit { return from event handler here }
+ end if
+
+ { The non-sensible code for all other subsequent notes would go here. }
+end on
+
+on release
+ dec($keysDown)
+end on
+
+ + Because the earlier statements are executed in an event handler, the higher + the chance that they will never get auto suspended. And with those couple of + lines in the latter example you might even be lucky that it won't ever get + suspended in that sensible code section at least. However when it comes to live + concerts you don't really want to depend on luck, and in practice such a + sensible code section might be bigger than this one. +
+
+ That's why we introduced synchronized code blocks for the
+ NKSP language, which have the following form:
+
+synchronized
+
+ ??statements??
+
+end synchronized
+
+
+ All ??statements?? which you put into such a synchronized
+ code block are guaranteed that they will never get auto suspended by
+ the sampler.
+
synchronized blocks are a language extension which
+ is only available with NKSP and requires at least LinuxSampler 2.0.0.svn60
+ or higher. KSP does not support synchronized blocks.
+ + So to make our previous example concurrency safe, we would + change it like this: +
+
+on init
+ declare $keysDown
+ declare $firstNoteID
+ declare $firstNoteNr
+ declare $firstVelocity
+end on
+
+on note
+ { The concurrency sensible code section for the "first active" note. }
+ synchronized
+ inc($keysDown)
+ if ($keysDown = 1 or event_status($firstNoteID) = $EVENT_STATUS_INACTIVE)
+ $firstNoteID = $EVENT_ID
+ $firstNoteNr = $EVENT_NOTE
+ $firstVelocity = $EVENT_VELOCITY
+ exit { return from event handler here }
+ end if
+ end synchronized
+
+ { The non-sensible code for all other subsequent notes would go here. }
+end on
+
+on release
+ dec($keysDown)
+end on
+
+ + If you are already familiar with some programming languages, then you + might already have seen such synchronized code block concepts + in languages like i.e. Java. This technique really provides an easy way + to protect certain sections of your script against concurrency issues. +
+synchronized code blocks only with great
+ care! If the amount of statements being executed in your synchronized block
+ is too large, then you will get audio dropouts. If you even use loops in
+ synchronized code blocks, then the entire sampler might even become
+ unresponsive in case your script is buggy!
+ A programming language provides so called operators to perform