| 1019 |
substantially differs calling built-in functions from calling user functions. |
substantially differs calling built-in functions from calling user functions. |
| 1020 |
</p> |
</p> |
| 1021 |
|
|
| 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 |
| 1063 |
|
|
| 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 |
| 1073 |
|
|
| 1074 |
|
{ The non-sensible code for all other subsequent notes would go here. } |
| 1075 |
|
end on |
| 1076 |
|
|
| 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 |
| 1095 |
|
|
| 1096 |
|
??statements?? |
| 1097 |
|
|
| 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 |
| 1121 |
|
|
| 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 |
| 1133 |
|
|
| 1134 |
|
{ The non-sensible code for all other subsequent notes would go here. } |
| 1135 |
|
end on |
| 1136 |
|
|
| 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> |
| 1154 |
|
|
| 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 |
Parent Directory
| 
Revision Log
| 
Patch