concurrency.md

### Concurrency Functions

#### startthread

Starts a thread that executes the passed callback. Immediately returns a special
result object, that can be used with #link: awaitresult#, to get the value returned
from the callback, after it has finished execution in the thread. This can also
be used with #link: killthread# to stop the execution of a thread.

Example:
```
proc thread1(threadname)
  for i = 1 to 10
    println(threadname)
    wait(1)
  endfor
endproc

proc thread2(threadname)
  for i = 1 to 10
    println(threadname)
    wait(1)
  endfor
endproc

let t1 = startthread(thread1, "thread 1")
let t2 = startthread(thread2, "thread 2")
await(t1)
await(t2)
getkey()

-- Outputs:

-- thread 1
-- thread 2
-- thread 2
-- thread 1
-- thread 2
-- thread 1
-- thread 1
-- thread 2
-- thread 2
-- thread 1
-- thread 1
-- thread 2
-- thread 2
-- thread 1
-- thread 2
-- thread 1
-- thread 1
-- thread 2
-- thread 1
-- thread 2

```

#### killthread

Kill a thread using the thread info object returned by the `startthread` function.

Example:

```
proc thread1(threadname)
loop
    println("loop")
    wait(1)
  endloop
endproc

let t1 = startthread(thread1, "thread 1")
wait(3) -- Wait 3 seconds
killthread(t1)
println("Thread killed")
getkey()

-- Outputs:

-- loop
-- loop
-- loop
-- Thread killed
```

#### awaitresult

Wait till the procedure in corresponding thread finish executing and return the result.

Example:

```
proc thread1(threadname)
wait(3)
return 100
endproc

let t1 = startthread(thread1, "thread 1")
println("Thread started, waiting for result...")
println(awaitresult(t1))
getkey()

-- Outputs
-- Thread started, waiting for result...
-- 100

```

#### await

Just wait till the procedure in corresponding thread finish executing. Does not expect the
thread callback to return a value.

```
proc thread1(threadname)
  wait(3)
endproc

let t1 = startthread(thread1, "thread 1")
println("Thread started, waiting to end...")
await(t1)
println("Thread finished")
getkey()

-- Outputs
-- Thread started, waiting to end...
-- Thread finished
```

#### newchannel

Create a new channel for communication with threads.

#### writechannel

Write a value to a channel

#### readchannel

Wait till a value is available on a channel, and return it when it is available.

#### newref

Get a new mutable reference.

#### readref

Get the current value of the mutable reference.

#### writeref

Write a new value to the mutable reference.

#### modifyref

Modify the current value of the mutable reference by a call back. The call back
gets the current value, and should return the modified value.

Example:

Increments a counter in a mutable reference in two threads.

```
proc thread1(ref)
  for i = 1 to 50000
    modifyref(ref, fn (x) (x + 1) endfn)
  endfor
endproc

proc thread2(ref)
  for i = 1 to 50000
    modifyref(ref, fn (x) (x + 1) endfn)
  endfor
endproc
let r = newref(0)
let t1 = startthread(thread1, r)
let t2 = startthread(thread2, r)
await(t1)
await(t2)
println(readref(r))
-- Prints 100000
getkey()
```