2020-06-28 14:58:08 +03:00
|
|
|
# V Work In Progress
|
|
|
|
|
|
|
|
***This document describes features that are not implemented, yet.
|
|
|
|
Please refer to [docs.md](https://github.com/vlang/v/blob/master/doc/docs.md)
|
|
|
|
for the current state of V***
|
|
|
|
|
|
|
|
## Table of Contents
|
|
|
|
|
|
|
|
* [Concurrency](#concurrency)
|
2020-07-11 00:45:03 +03:00
|
|
|
* [Variable Declarations](#variable-declarations)
|
|
|
|
* [Strengths](#strengths)
|
|
|
|
* [Weaknesses](#weaknesses)
|
|
|
|
* [Compatibility](#compatibility)
|
|
|
|
* [Automatic Lock](#automatic-lock)
|
2020-08-06 16:28:19 +03:00
|
|
|
* [Channels](#channels)
|
2020-06-28 14:58:08 +03:00
|
|
|
|
|
|
|
## Concurrency
|
|
|
|
|
|
|
|
### Variable Declarations
|
|
|
|
|
|
|
|
Objects that are supposed to be used to exchange data between
|
|
|
|
coroutines have to be declared with special care. Exactly one of the following
|
|
|
|
4 kinds of declaration has to be chosen:
|
|
|
|
|
|
|
|
```v
|
|
|
|
a := ...
|
|
|
|
mut b := ...
|
|
|
|
shared c := ...
|
|
|
|
atomic d := ...
|
|
|
|
```
|
|
|
|
|
|
|
|
- `a` is declared as *constant* that can be passed to
|
|
|
|
other coroutines and read without limitations. However
|
|
|
|
it cannot be changed.
|
|
|
|
- `b` can be accessed reading and writing but only from one
|
|
|
|
coroutine. That coroutine *owns* the object. A `mut` variable can
|
|
|
|
be passed to another coroutine (as receiver or function argument in
|
|
|
|
the `go` statement or via a channel) but then ownership is passed,
|
|
|
|
too, and only the other coroutine can access the object.<sup>1</sup>
|
|
|
|
- `c` can be passed to coroutines an accessed
|
|
|
|
*concurrently*.<sup>2</sup> In order to avoid data races it has to
|
|
|
|
be locked before access can occur and unlocked to allow access to
|
2020-07-07 02:57:31 +03:00
|
|
|
other coroutines. This is done by one the following block structures:
|
2020-06-28 14:58:08 +03:00
|
|
|
```v
|
|
|
|
lock c {
|
|
|
|
// read, modify, write c
|
|
|
|
...
|
|
|
|
}
|
|
|
|
```
|
2020-07-07 02:57:31 +03:00
|
|
|
|
|
|
|
```v
|
|
|
|
rlock c {
|
|
|
|
// read c
|
|
|
|
...
|
|
|
|
}
|
|
|
|
```
|
2020-06-28 14:58:08 +03:00
|
|
|
Several variables may be specified: `lock x, y, z { ... }`.
|
|
|
|
They are unlocked in the opposite order.
|
|
|
|
- `d` can be passed to coroutines and accessed *concurrently*,
|
|
|
|
too.<sup>3</sup> No lock is needed in this case, however
|
|
|
|
`atomic` variables can only be 32/64 bit integers (or pointers)
|
|
|
|
and access is limited to a small set of predefined idioms that have
|
|
|
|
native hardware support.
|
|
|
|
|
|
|
|
To help making the correct decision the following table summarizes the
|
|
|
|
different capabilities:
|
|
|
|
|
|
|
|
| | *default* | `mut` | `shared` | `atomic` |
|
|
|
|
| :--- | :---: | :---: | :---: | :---: |
|
|
|
|
| write access | | + | + | + |
|
|
|
|
| concurrent access | + | | + | + |
|
|
|
|
| performance | ++ | ++ | | + |
|
|
|
|
| sophisticated operations | + | + | + | |
|
|
|
|
| structured data types | + | + | + | |
|
|
|
|
|
|
|
|
### Strengths
|
|
|
|
#### default
|
|
|
|
- very fast
|
|
|
|
- unlimited access from different coroutines
|
|
|
|
- easy to handle
|
|
|
|
|
|
|
|
#### `mut`
|
|
|
|
- very fast
|
|
|
|
- easy to handle
|
|
|
|
|
|
|
|
#### `shared`
|
|
|
|
- concurrent access from different coroutines
|
|
|
|
- data type may be complex structure
|
|
|
|
- sophisticated access possible (several statements within one `lock`
|
|
|
|
block)
|
|
|
|
|
|
|
|
#### `atomic`
|
|
|
|
- concurrent access from different coroutines
|
|
|
|
- reasonably fast
|
|
|
|
|
|
|
|
### Weaknesses
|
|
|
|
#### default
|
|
|
|
- read only
|
|
|
|
|
|
|
|
#### `mut`
|
|
|
|
- access only from one coroutine at a time
|
|
|
|
|
|
|
|
#### `shared`
|
|
|
|
- lock/unlock are slow
|
|
|
|
- moderately difficult to handle (needs `lock` block)
|
|
|
|
|
|
|
|
#### `atomic`
|
|
|
|
- limited to single (max. 64 bit) integers (and pointers)
|
|
|
|
- only a small set of predefined operations possible
|
|
|
|
- very difficult to handle correctly
|
|
|
|
|
|
|
|
<sup>1</sup> The owning coroutine will also free the memory space used
|
|
|
|
for the object when it is no longer needed.
|
|
|
|
<sup>2</sup> For `shared` objects the compiler adds code for reference
|
|
|
|
counting. Once the counter reaches 0 the object is automatically freed.
|
|
|
|
<sup>3</sup> Since an `atomic` variable is only a few bytes in size
|
|
|
|
allocation would be an unnecessary overhead. Instead the compiler
|
|
|
|
creates a global.
|
2020-07-11 00:45:03 +03:00
|
|
|
|
|
|
|
### Compatibility
|
|
|
|
Outside of `lock`/`rlock` blocks function arguments must in general
|
|
|
|
match - with the familiar exception that objects declared `mut` can be
|
|
|
|
used to call functions expecting immutable arguments:
|
|
|
|
|
|
|
|
```v
|
|
|
|
fn f(x St) {...}
|
|
|
|
fn g(mut x St) {...}
|
|
|
|
fn h(shared x St) {...}
|
|
|
|
fn i(atomic x u64) {...}
|
|
|
|
|
|
|
|
a := St{...}
|
|
|
|
f(a)
|
|
|
|
|
|
|
|
mut b := &St{...} // reference since transferred to coroutine
|
|
|
|
f(b)
|
|
|
|
go g(mut b)
|
|
|
|
// `b` should not be accessed here any more
|
|
|
|
|
|
|
|
shared c := &St{...}
|
|
|
|
h(shared c)
|
|
|
|
|
|
|
|
atomic d &u64
|
|
|
|
i(atomic d)
|
|
|
|
```
|
|
|
|
|
|
|
|
Inside a `lock c {...}` block `c` behaves like a `mut`,
|
|
|
|
inside an `rlock c {...}` block like an immutable:
|
|
|
|
```v
|
|
|
|
shared c := &St{...}
|
|
|
|
lock c {
|
|
|
|
g(mut c)
|
|
|
|
f(c)
|
|
|
|
// call to h() not allowed inside `lock` block
|
|
|
|
// since h() will lock `c` itself
|
|
|
|
}
|
|
|
|
rlock c {
|
|
|
|
f(c)
|
|
|
|
// call to g() or h() not allowed
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Automatic Lock
|
|
|
|
In general the compiler will generate an error message when a `shared`
|
|
|
|
object is accessed outside of any corresponding `lock`/`rlock`
|
|
|
|
block. However in simple and obvious cases the necessary lock/unlock
|
|
|
|
can be generated automatically for `array`/`map` operations:
|
|
|
|
|
|
|
|
```v
|
|
|
|
shared a []int{...}
|
|
|
|
go h2(shared a)
|
|
|
|
a << 3
|
|
|
|
// keep in mind that `h2()` could change `a` between these statements
|
|
|
|
a << 4
|
|
|
|
x := a[1] // not necessarily `4`
|
|
|
|
|
|
|
|
shared b map[string]int
|
|
|
|
go h3(shared b)
|
|
|
|
b['apple'] = 3
|
|
|
|
c['plume'] = 7
|
|
|
|
y := b['apple'] // not necesarily `3`
|
|
|
|
|
|
|
|
// iteration over elements
|
|
|
|
for k, v in b {
|
|
|
|
// concurrently changed k/v pairs may or my not be included
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
This is handy, but since other coroutines might access the `array`/`map`
|
|
|
|
concurrently between the automatically locked statements, the results
|
|
|
|
are sometimes surprising. Each statement should be seen as a single
|
|
|
|
transaction that is unrelated to the previous or following
|
|
|
|
statement. Therefore - but also for performance reasons - it's often
|
|
|
|
better to group consecutive coherent statements in an explicit `lock` block.
|
2020-08-06 16:28:19 +03:00
|
|
|
|
|
|
|
### Channels
|
|
|
|
Channels in V work basically like those in Go. You can `push()` objects into
|
|
|
|
a channel and `pop()` objects from a channel. They can be buffered or unbuffered
|
|
|
|
and it is possible to `select` from multiple channels.
|
|
|
|
|
|
|
|
#### Syntax and Usage
|
|
|
|
There is no support for channels in the core language (yet), so all functions
|
|
|
|
are in the `sync` library. Channels must be created as `mut` objects.
|
|
|
|
|
|
|
|
```v
|
|
|
|
mut ch := sync.new_channel<int>(0) // unbuffered
|
|
|
|
mut ch2 := sync.new_channel<f64>(100) // buffer length 100
|
|
|
|
```
|
|
|
|
|
|
|
|
Channels can be passed to coroutines like normal `mut` variables:
|
|
|
|
|
|
|
|
```v
|
|
|
|
fn f(mut ch sync.Channel) {
|
|
|
|
...
|
|
|
|
}
|
|
|
|
|
|
|
|
fn main() {
|
|
|
|
...
|
|
|
|
go f(mut ch)
|
|
|
|
...
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
The routines `push()` and `pop()` both use *references* to objects. This way
|
|
|
|
unnecessary copies of large objects are avoided and the call to `cannel_select()`
|
|
|
|
(see below) is simpler:
|
|
|
|
|
|
|
|
```v
|
|
|
|
n := 5
|
|
|
|
x := 7.3
|
|
|
|
ch.push(&n)
|
|
|
|
ch2.push(&x)
|
|
|
|
|
|
|
|
mut m := int(0)
|
|
|
|
mut y := f64(0.0)
|
|
|
|
ch.pop(&m)
|
|
|
|
ch2.pop(&y)
|
|
|
|
```
|
|
|
|
|
2020-08-10 07:22:20 +03:00
|
|
|
A channel can be closed to indicate that no further objects can be pushed. Any attempt
|
|
|
|
to do so will then result in a runtime panic. The `pop()` method will return immediately `false`
|
|
|
|
if the associated channel has been closed and the buffer is empty.
|
|
|
|
|
|
|
|
```v
|
|
|
|
ch.close()
|
|
|
|
...
|
|
|
|
if ch.pop(&m) {
|
|
|
|
println('got $m')
|
|
|
|
} else {
|
|
|
|
println('channel has been closed')
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2020-08-06 16:28:19 +03:00
|
|
|
The select call is somewhat tricky. The `channel_select()` function needs three arrays that
|
|
|
|
contain the channels, the directions (pop/push) and the object references and
|
|
|
|
a timeout of type `time.Duration` (or `0` to wait unlimited) as parameters. It returns the
|
|
|
|
index of the object that was pushed or popped or `-1` for timeout.
|
|
|
|
|
|
|
|
```v
|
2020-08-10 07:22:20 +03:00
|
|
|
mut chans := [ch, ch2] // the channels to monitor
|
|
|
|
directions := [sync.Direction.pop, .pop] // .push or .pop
|
|
|
|
mut objs := [voidptr(&m), &y] // the objects to push or pop
|
2020-08-06 16:28:19 +03:00
|
|
|
|
|
|
|
// idx contains the index of the object that was pushed or popped, -1 means timeout occured
|
|
|
|
idx := sync.channel_select(mut chans, directions, mut objs, 0) // wait unlimited
|
|
|
|
match idx {
|
|
|
|
0 {
|
|
|
|
println('got $m')
|
|
|
|
}
|
|
|
|
1 {
|
|
|
|
println('got $y')
|
|
|
|
}
|
|
|
|
else {
|
|
|
|
// idx = -1
|
|
|
|
println('Timeout')
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
2020-08-10 07:22:20 +03:00
|
|
|
If all channels have been closed `-2` is returned as index.
|