ViewVC logotype

Diff of /doc/docbase/instrument_scripts/nksp/01_nksp.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 3261 by schoenebeck, Fri May 19 15:19:37 2017 UTC revision 3262 by schoenebeck, Wed May 31 23:19:39 2017 UTC
# Line 1019  end on Line 1019  end on
1019        substantially differs calling built-in functions from calling user functions.        substantially differs calling built-in functions from calling user functions.
1020      </p>      </p>
1022        <h3>Synchronized Blocks</h3>
1023        <p>
1024          When we introduced the <a href="polyphonic_variables">polyphonic keyword</a>
1025          previously, we learned that a script may automatically be suspended by
1026          the sampler at any time and then your script is thus sleeping for an
1027          arbitrary while. The sampler must do such auto suspensions under certain
1028          situations in cases where an instrument script may become a hazard for the
1029          sampler's overall real-time stability. If the sampler would not do so, then
1030          instrument scripts might easily cause audio dropouts, or at worst, buggy
1031          instrument scripts might even lock up the entire sampler in an endless
1032          loop. So auto suspension is an essential feature of the sampler's real-time
1033          instrument script engine.
1034        </p>
1035        <p>
1036          Now the problem as a script author is that you don't really know beforehand
1037          why and when your script might get auto suspended by the sampler. And when
1038          you are working on more complex, sophisticated scripts, you will notice
1039          that this might indeed be a big problem in certain sections of your scripts.
1040          Because in practice, a sophisticated script often has at least one certain
1041          consecutive portion of statements which must be executed in strict consecutive order
1042          by the sampler, which might otherwise cause concurrency issues and thus
1043          misbehavior of your script if that sensible code section was auto suspended
1044          in between. A typical example of such concurrency sensible code sections are
1045          statements which are reading and conditionally modifying global variables.
1046          If your script gets auto suspended in such a code section, another
1047          script handler instance might then interfere and change those global
1048          variables in between.
1049        </p>
1050        <p>
1051          To avoid that, you can place such a sensible code section at the very beginning
1052          of your event handler. For example consider you might be writing a custom
1053          <i title="A consecutive pitch glide from one note to another note.">glissando</i>
1054          script starting like this:
1055        </p>
1056        <code>
1057    on init
1058      declare $keysDown
1059      declare $firstNoteID
1060      declare $firstNoteNr
1061      declare $firstVelocity
1062    end on
1064    on note
1065      { The concurrency sensible code section for the "first active" note. }
1066      inc($keysDown)
1067      if ($keysDown = 1 or event_status($firstNoteID) = $EVENT_STATUS_INACTIVE)
1068        $firstNoteID = $EVENT_ID
1069        $firstNoteNr = $EVENT_NOTE
1070        $firstVelocity = $EVENT_VELOCITY
1071        exit { return from event handler here }
1072      end if
1074      { The non-sensible code for all other subsequent notes would go here. }
1075    end on
1077    on release
1078      dec($keysDown)
1079    end on
1080        </code>
1081        <p>
1082          Because the earlier statements are executed in an event handler, the higher
1083          the chance that they will never get auto suspended. And with those couple of
1084          lines in the latter example you might even be lucky that it won't ever get
1085          suspended in that sensible code section at least. However when it comes to live
1086          concerts you don't really want to depend on luck, and in practice such a
1087          sensible code section might be bigger than this one.
1088        </p>
1089        <p>
1090          That's why we introduced <code>synchronized</code> code blocks for the
1091          NKSP language, which have the following form:
1092        </p>
1093        <code>
1094    synchronized
1096      ??statements??
1098    end synchronized
1099        </code>
1100        <p>
1101          All <code>??statements??</code> which you put into such a synchronized
1102          code block are guaranteed that they will never get auto suspended by
1103          the sampler.
1104        </p>
1105        <note>
1106          Such <code>synchronized</code> blocks are a language extension which
1107          is only available with NKSP and requires at least LinuxSampler 2.0.0.svn60
1108          or higher. KSP does not support <code>synchronized</code> blocks.
1109        </note>
1110        <p>
1111          So to make our previous example concurrency safe, we would
1112          change it like this:
1113        </p>
1114        <code>
1115    on init
1116      declare $keysDown
1117      declare $firstNoteID
1118      declare $firstNoteNr
1119      declare $firstVelocity
1120    end on
1122    on note
1123      { The concurrency sensible code section for the "first active" note. }
1124      synchronized
1125        inc($keysDown)
1126        if ($keysDown = 1 or event_status($firstNoteID) = $EVENT_STATUS_INACTIVE)
1127          $firstNoteID = $EVENT_ID
1128          $firstNoteNr = $EVENT_NOTE
1129          $firstVelocity = $EVENT_VELOCITY
1130          exit { return from event handler here }
1131        end if
1132      end synchronized
1134      { The non-sensible code for all other subsequent notes would go here. }
1135    end on
1137    on release
1138      dec($keysDown)
1139    end on
1140        </code>
1141        <p>
1142          If you are already familiar with some programming languages, then you
1143          might already have seen such synchronized code block concepts
1144          in languages like i.e. Java. This technique really provides an easy way
1145          to protect certain sections of your script against concurrency issues.
1146        </p>
1147        <note class="important">
1148          You <b>must</b> use such <code>synchronized</code> code blocks only with great
1149          care! If the amount of statements being executed in your synchronized block
1150          is too large, then you will get audio dropouts. If you even use loops in
1151          synchronized code blocks, then the entire sampler might even become
1152          unresponsive in case your script is buggy!
1153        </note>
1155      <h2>Operators</h2>      <h2>Operators</h2>
1156      <p>      <p>
1157        A programming language provides so called <i>operators</i> to perform        A programming language provides so called <i>operators</i> to perform

Removed from v.3261  
changed lines
  Added in v.3262

  ViewVC Help
Powered by ViewVC