Skip to content

Commit f6bbfd5

Browse files
committed
Merge remote-tracking branch 'origin/master'
2 parents a4da04d + 58f7fdb commit f6bbfd5

File tree

1 file changed

+208
-0
lines changed

1 file changed

+208
-0
lines changed

structures/expressions/variables.md

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ Some types of variable have special behaviour in certain situations, detailed be
1414

1515
Most variables are **value** variables: these store a raw value. Value variables have the standard `{variable}` name pattern.
1616

17+
Normal (value) variables are local to the current `trigger` section.
18+
1719
Variables can be set and retrieved like a normal expression.
1820

1921
```clike
@@ -167,3 +169,209 @@ This would allow an atomic variable to be returned from a function secretly, but
167169
{% hint style="danger" %}
168170
This will be an `AtomicVariable` object and may be difficult to manipulate.
169171
{% endhint %}
172+
173+
### Thread-Local Variables
174+
175+
Thread-local variables use the `{_variable}` name pattern. They are **reference** variables.
176+
177+
Thread-local variables are accessible **anywhere** on the current process (thread). This includes other functions and lambdas. Thread-local variables are **not** accessible from other threads.
178+
179+
{% hint style="info" %}
180+
A thread/process is like a queue of instructions, executed in order. Using the `wait` or `sleep`effect will pause the thread.
181+
182+
The `run ... in the background` effect can be used to create a different, branching process that will run at the same time as the current one.
183+
{% endhint %}
184+
185+
In normal code, thread-local variables function exactly the same as regular value variables.
186+
187+
```clike
188+
set {_var} to 100
189+
set {_var} to {_var} - 1
190+
print {_var}
191+
if {_var} is 6:
192+
set {_var} to 20
193+
```
194+
195+
Remember: a variable named `{_var}` is **different** from a variable named `{var}`.
196+
197+
```clike
198+
set {_var} to 1 // thread-local
199+
set {var} to 2 // normal
200+
assert {var} is not {_var}
201+
```
202+
203+
Thread-local variables make it easy to pass data between triggers that are guaranteed to be executed in the same process.
204+
205+
```clike
206+
function first:
207+
trigger:
208+
set {_var} to 10 // thread-local
209+
set {var} to 5 // normal (local to this trigger)
210+
run second()
211+
212+
function second:
213+
trigger:
214+
assert {var} is null
215+
assert {_var} is 10 // value is kept from before call
216+
```
217+
218+
Thread-local variables are **atomic**, and any use alters the same copy of the variable.
219+
220+
```clike
221+
function first:
222+
trigger:
223+
set {_var} to 10 // thread-local
224+
assert {_var} is 10
225+
run second() // value is changed in this function
226+
assert {_var} is 5
227+
228+
function second:
229+
trigger:
230+
assert {_var} is 10
231+
set {_var} to 5
232+
assert {_var} is 5
233+
```
234+
235+
Thread-local variables can be accessed and changed from lambdas, unlike regular variables.
236+
237+
```clike
238+
function my_function:
239+
trigger:
240+
set {_var} to 10 // thread-local
241+
set {thing} to a new runnable:
242+
assert {_var} is 10
243+
set {_var} to 5
244+
assert {_var} is 5
245+
assert {_var} is 10
246+
run {thing} // value is changed by the runnable
247+
assert {_var} is 5
248+
```
249+
250+
However, lambdas or functions run in the background will **not** be able to access the value.
251+
252+
This is because background processes are run on a **different** thread, so their thread-local `{_variables}` are different.
253+
254+
```clike
255+
function my_function:
256+
trigger:
257+
set {_var} to 10 // thread-local
258+
set {thing} to a new runnable:
259+
assert {_var} is null
260+
set {_var} to 5 // does NOT update the other _var
261+
assert {_var} is 5
262+
assert {_var} is 10
263+
run {thing} in the background // run on a DIFFERENT thread
264+
wait 10 milliseconds // wait for other thread to finish
265+
assert {_var} is 10 // _var is unchanged
266+
```
267+
268+
Events and other entry-points are triggered on a new thread, so there is no cross-contamination between processes.
269+
270+
```clike
271+
on load:
272+
trigger:
273+
assert {_var} is null // not set yet
274+
set {_var} to 10 // thread-local
275+
assert {_var} is 10
276+
277+
on load: // different event trigger, so run on different thread
278+
trigger:
279+
assert {_var} is null // not set on THIS thread
280+
set {_var} to 10 // thread-local
281+
assert {_var} is 10
282+
```
283+
284+
The [skript namespace ](../../namespaces/skript.md#generic)has a special function to transfer thread-local variables to a different thread.
285+
286+
Transferring these will **copy** the variables, so the original copy will not be updated by changes.
287+
288+
```clike
289+
function my_function:
290+
trigger:
291+
set {thread} to the current process
292+
set {_var} to 10 // thread-local
293+
set {thing} to a new runnable:
294+
run copy_threadlocals_from({thread})
295+
assert {_var} is 10 // copied from other _var
296+
set {_var} to 5 // does NOT update the other _var
297+
assert {_var} is 5
298+
assert {_var} is 10
299+
run {thing} in the background // run on a DIFFERENT thread
300+
assert {_var} is 10 // _var is unchanged, the COPY was changed
301+
```
302+
303+
### Global Variables
304+
305+
Global variables use the `{!variable}` name pattern. They are **reference** variables. These are most similar to the normal variables from [original Skript](https://github.com/SkriptLang/Skipt).
306+
307+
Any copy of a global `{!variable}` anywhere on any process will access the same value.
308+
309+
{% hint style="info" %}
310+
Unlike in original Skript, global variables are not persistent across restarts (by default.)
311+
{% endhint %}
312+
313+
In normal code, globals variables function exactly the same as regular value variables.
314+
315+
```clike
316+
set {!var} to 100
317+
set {!var} to {!var} - 1
318+
print {!var}
319+
if {!var} is 6:
320+
set {!var} to 20
321+
```
322+
323+
Remember: a variable named `{!var}` is **different** from a variable named `{var}`.
324+
325+
```clike
326+
set {!var} to 1 // global
327+
set {var} to 2 // normal
328+
assert {var} is not {!var}
329+
```
330+
331+
Global variables make it easy to pass data between triggers and entire scripts.
332+
333+
```clike
334+
function first:
335+
trigger:
336+
set {!var} to 10 // thread-local
337+
set {var} to 5 // normal (local to this trigger)
338+
run second()
339+
340+
function second:
341+
trigger:
342+
assert {var} is null
343+
assert {!var} is 10 // value is kept from before call
344+
```
345+
346+
Global variables are **atomic** and can be accessed and changed from other triggers, lambdas and different threads, unlike regular variables.
347+
348+
```clike
349+
function my_function:
350+
trigger:
351+
set {!var} to 10 // thread-local
352+
set {thing} to a new runnable:
353+
assert {!var} is 10
354+
set {!var} to 5
355+
assert {!var} is 5
356+
assert {!var} is 10
357+
run {thing} in the background // value is changed by the runnable
358+
wait 10 milliseconds // wait for other thread to finish
359+
assert {!var} is 5
360+
```
361+
362+
Global variables are accessible from **any** process.
363+
364+
```clike
365+
on load:
366+
trigger:
367+
assert {!var} is null // not set yet
368+
set {!var} to 10 // global
369+
assert {!var} is 10
370+
371+
on load: // different event trigger, so run on different thread
372+
trigger:
373+
wait 10 milliseconds // wait for previous trigger to finish
374+
assert {!var} is 10 // set everywhere
375+
set {!var} to 5 al
376+
assert {!var} is 5
377+
```

0 commit comments

Comments
 (0)