From f5c4671bfbad96bf346bd7e9a21fc4317b4959df Mon Sep 17 00:00:00 2001
From: Indrajith K L
Date: Sat, 3 Dec 2022 17:00:20 +0530
Subject: Adds most of the tools
---
v_windows/v/old/doc/upcoming.md | 195 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 195 insertions(+)
create mode 100644 v_windows/v/old/doc/upcoming.md
(limited to 'v_windows/v/old/doc/upcoming.md')
diff --git a/v_windows/v/old/doc/upcoming.md b/v_windows/v/old/doc/upcoming.md
new file mode 100644
index 0000000..45a1d98
--- /dev/null
+++ b/v_windows/v/old/doc/upcoming.md
@@ -0,0 +1,195 @@
+# 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)
+ * [Variable Declarations](#variable-declarations)
+ * [Strengths](#strengths)
+ * [Weaknesses](#weaknesses)
+ * [Compatibility](#compatibility)
+ * [Automatic Lock](#automatic-lock)
+ * [Channels](#channels)
+
+## 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 ignore
+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.1
+- `c` can be passed to coroutines an accessed
+ *concurrently*.2 In order to avoid data races it has to
+ be locked before access can occur and unlocked to allow access to
+ other coroutines. This is done by one the following block structures:
+ ```v ignore
+ lock c {
+ // read, modify, write c
+ ...
+ }
+ ```
+
+ ```v ignore
+ rlock c {
+ // read c
+ ...
+ }
+ ```
+ 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.3 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
+
+1 The owning coroutine will also free the memory space used
+for the object when it is no longer needed.
+2 For `shared` objects the compiler adds code for reference
+counting. Once the counter reaches 0 the object is automatically freed.
+3 Since an `atomic` variable is only a few bytes in size
+allocation would be an unnecessary overhead. Instead the compiler
+creates a global.
+
+### 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 ignore
+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{...}
+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 ignore
+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 ignore
+shared a := []int{cap: 5}
+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.
+
+### Channels
--
cgit v1.2.3