Updated docs.

Author: k2u2

docs/README.md

@@ -0,0 +1,9 @@
+# golib/weak_ref ライブラリ
+
+弱参照(弱い参照/weak reference)の機能を提供します。
+
+* [weak_ref.WeakRef](WeakRef.md)
+  * Lock-freeな弱参照の機能を提供します。
+
+* [弱参照(弱い参照/weak reference)の解説](weak_reference.md)
+	* go言語に限定しない一般的な弱参照の説明です。

docs/WeakRef.md

@@ -0,0 +1,96 @@
+# type WeakRef
+弱参照の機能を提供するモジュールです。  
+atomic操作で排他制御を行っているので、Lock-freeです。
+
+## import
+
+```go
+import "github.com/l4go/weak_ref"
+```
+vendoringして使うことを推奨します。
+
+## 利用サンプル
+
+* [弱参照のサンプル](../examples/ex_weak_ref/ex_weak_ref.go)
+* [所有権譲渡のサンプル](../examples/ex_ref_move/ex_ref_move.go)
+* [CAS処理のサンプル](../examples/ex_ref_cas/ex_ref_cas.go)
+* [CAS処理のループを自前で書いたサンプル](../examples/ex_ref_cas2/ex_ref_cas2.go)
+
+## 参照の扱い
+\*WeakRefでの参照の扱いは以下の通りです。
+
+* 参照は、ポインタ型の値で表現する。
+* 内部へ保存された参照へのアクセスは、atomic操作で行う。
+* 参照を無効化でき、nil値を無効状態を示すものとして扱う。
+* 入力では、参照のポインタ型の値を`interface{}`で受け取る。
+* 出力では、参照のポインタ型の値を`interface{}`として返す。
+* 初期化時(New()時)に、参照の型を固定する。(静的な型アサーションが利用可能)
+
+## メソッド概略
+
+### func New(val interface{}) \*WeakRef
+\*WeakRefを生成します。
+参照の利用終了時に、無効にする(Reset()等)ことで弱参照として動作します。  
+初期値を使って、値の設定だけでなく、参照の型を固定化も行います。初期化後は、初期値と異なる型の値を入力するとpanicします。
+
+初期値だけは型情報が必要なので、nil型のnil値が利用できません。無効状態(nil値)に初期化したい場合は、以下の例のように型ありのnil値を利用してください。
+
+ポインタ型のnil値(無効状態)で初期化する例
+
+```go 
+type Test struct {
+	val int
+}
+
+var wr =  weak_ref.New((*Test)(nil))
+```
+
+### func (wr \*WeakRef) Move() \*WeakRef
+参照の所有権を譲渡した\*WeakRefを生成します。  
+元となった\*WeakRefは無効にされます。
+
+別の処理(関数など)へ、参照の管理ごと譲渡する用途を想定しています。
+
+### func (wr \*WeakRef) Reset()
+参照を無効にします。  
+弱参照として動作させるには、参照の利用が終了した際に、Reset()の呼び出しが必要です。
+
+### func (wr \*WeakRef) Get() interface{}
+参照の値を取得します。
+
+### func (wr \*WeakRef) Set(val interface{})
+参照の値を変更します。   
+静的なnilで無効化する場合は、簡素に記述できるReset()を利用するべきです。  
+goroutine間での排他制御が必要な場合は、CasUpdate()を利用してください。
+
+### func (wr \*WeakRef) Swap(new\_val interface{}) interface{}
+参照の値を更新し、変更前の値を返します。  
+goroutine間での排他制御が必要な場合は、CasUpdate()を利用してください。
+
+### func (wr \*WeakRef) CompareAndSwap(old\_val, new\_val interface{}) bool
+CAS(コンペア・アンド・スワップ、Compare-and-swap)での、参照の値の更新を試み、
+成功した場合はtureを、失敗した場合はfalseを返します。
+
+通常の用途では、より簡素に記述できるCasUpdate()を利用すべきです。
+
+### func (wr \*WeakRef) CasUpdate(f CasUpdateFunc) interface{}
+CASアルゴリズム(CAS方式のループを実施)で、参照の値を更新します。  
+変更後の値の計算方法をCasUpdateFunc型の関数で渡します。  
+参照が無効な場合は失敗し、nil値を返します。
+更新が成功した場合は変更後の値を返します。
+
+### type CasUpdateFunc func(v interface{}) interface{}
+CasUpdate()で利用する、古い値から新しい値への計算方法を記述する関数の型です。  
+CASアルゴリズムではコリジョン時に再計算が必要なため、CasUpdateFunc型の関数は、1回の更新処理で複数回呼ばれることがあります。
+
+インクリメントするCasUpdateFunc型の関数の例(`func incr()`)
+
+```go
+type Test struct {
+        V int
+}
+
+func incr(v interface{}) interface{} {
+        return &Test{V: v.V+1}
+}
+```

docs/one_ref.png

@@ -0,0 +1,98 @@
+go言語に限定しない一般的な弱参照の説明です。
+
+世の中に「弱参照」のまともな説明がすくないため、仕方なく暫定的に記述したものです。(詳細な理由については、末尾の補足を参照)
+
+# 弱参照(弱い参照/weak reference)
+弱参照は、参照先の変数(メモリ)の所有権を持たない参照です。  
+対語として、所有権のある本来の参照を「強参照(強い参照/strong reference)」と表現することがあります。  
+弱参照は、所有権を持たないので、参照先の変数の解放で自動的に無効化されます。
+また、処理中の無効化を回避するため、参照(強参照)への(一時的な)変換も可能です。
+
+## 弱参照で回避できる問題
+利用方法を知らないと弱参照の理解が難しいので、弱参照の利用方法についての記述します。
+
+参照を共有すると、条件によっては、メモリが適切に解放できくなる問題が発生します。  
+この問題を軽減するための手法の一つが弱参照になります。
+
+参照が共有されたことで、適切にメモリ解放ができなくなる問題を起こす状態には、主に以下の2種類です。
+
+1. 参照が相互に参照している。(循環参照)
+	* 参照から共有されている
+2. 終了が未定な処理が参照を保持している。
+	* 処理から共有されている
+
+構造的には、この2つは、参照を共有(保有)する対象が違うだけです。 
+弱参照を使うと、これらの共有状態を、メモリ管理からは共有されていないように見せかけることができ、問題を回避できるわけです。
+
+以降の説明では、それぞれの状態について、もう少し詳しく説明しておきます。
+
+### 1. 参照が相互に参照している状態(循環参照の状態)
+単一または複数の参照が、直接または間接的に、循環するように参照した状態です。
+
+この状態にしてしまうと、「参照カウンタ」方式のみメモリ管理では、参照の利用終了を認識できません。  
+処理が終了しても、循環分のカウンタ増で参照カウンタが0にならず、メモリ管理には利用中だと認識され、結果的にメモリリークが起こります。
+
+この問題は以下の3種類の方法で、回避可能です。
+
+* 後処理で(一部の)参照を無効にして、参照の循環を壊す。
+* 一部の参照を弱参照に代えて、メモリ管理的に循環がない状態にする。
+* 一部の参照をコピーした値に代えて、参照の循環がない状態にする。
+*  GCで循環参照を解放する(適切に動作するGCを利用する)。
+
+弱参照で解決する場合の以下の図のような参照関係の変更を行います。
+
+弱参照による問題回避の図1(1要素での循環参照の例)  
+![1要素での循環参照](one_ref.png)
+
+弱参照による問題回避の図2(複数要素での循環参照の例)  
+![2要素の循環参照](two_ref.png)
+
+弱参照を使うと、GCやデータコピー等の実行時のコストを軽減することができます。
+
+### 2. 終了が未定な処理が参照を保持している状態
+終了が未定な(処理時間が長い)処理に、参照としてデータを渡すと発生する状態です。  
+例えば、処理時間が長いコールバック関数や、動作し続けるサブシステムへ、参照を渡す(共有する)場合が該当します。  
+
+この状態になると、参照を渡した側(依頼元)の処理が終了しても、参照を渡された側(依頼先)の処理は中断されないと続行するので、参照も解放されません。
+処理も参照も、どちらも終われない状態になり、実質のメモリリーク状態と、実質の無限ループが起きてしまいます。
+
+この問題は以下のような2種類の方法で回避可能です。
+
+* 中断機能を実装し、依頼元の終了時に確実に実施する。
+* 弱参照でデータを渡し、依頼先の処理に参照を保持させない。
+* (コピーした値を渡しても、解決しない)
+* (実際に参照が利用されてるので、GCでは解決しない)
+* (解決せずに放置するプログラムもたまに見かける...)
+
+弱参照を使う場合、自動的に無効化する特徴によって、中断処理も実現が容易になります。
+
+弱参照による問題回避の図3(依頼先の処理も参照を保有する例)  
+![依頼先の処理が保有](proc_ref.png)
+
+この問題はGCでは回避できないので、弱参照を使うしかないことがあります。
+
+# 補足(こんな説明が存在する理由)
+
+## GC(ガベージコレクション/garbage collection)の定義
+前提として、以下のGCの定義を信じると、きちんと「不要になった領域を自動的に解放しない」機能をGCとして書くのは、誤解を生むので、解説としては不適切と判断しています。
+
+Wikipediaより(2021/12/15現在)
+> ガベージコレクション（英: garbage collection; GC）とは、コンピュータプログラムが動的に確保したメモリ領域のうち、不要になった領域を自動的に解放する機能である。
+
+この定義は、LISPから始まるGCの歴史もきちんと踏まえて書かれて、十分信用できそうです。  
+そして、この定義に従うなら、「循環参照を自動的に解放できない」メモリ管理は、GCとは言い難いのです。
+そうなると、「参照カウンタ」のみに頼ったメモリ管理も、やはりGCとは言い難いのです。
+
+## 世の「弱参照」
+
+そして、上記のGCの定義を理解した上で、世の中の「弱参照」の定義らしき説明を読むと、何かおかしいのです。  
+例えば、Wikipediaの説明すら、以下の通りです。
+
+Wikipediaより(2021/12/15現在)
+> 弱い参照（英: weak reference、ウィークリファレンス）あるいは弱参照とは、参照先のオブジェクトをガベージコレクタから守ることのできない参照のことである。
+
+実際に、GCがない処理系でも弱参照は使われていて、弱参照はGC専用の仕組みではありません。
+そうすると、上記の、GCを前提とした弱参照の説明は、明らかに間違っています。  
+このような状況なので、仕方なく書いたのがこの説明です。
+
+おそらく、GCのある処理系での弱参照の「動き」を理解した方が、「弱参照」自体を十分に理解しないまま、使ってる言語の「動き」を文章にした結果、このような状況になっていると予想されます。残念な話です。

docs/proc_ref.png

@@ -0,0 +1,66 @@
+package main
+
+import (
+	"log"
+	"time"
+
+	"github.com/l4go/task"
+	"github.com/l4go/weak_ref"
+)
+
+type Test struct {
+	v uint64
+}
+
+func NewTest(i uint64) *Test {
+	return &Test{v: i}
+}
+func (t *Test) Value() uint64 {
+	return t.v
+}
+
+func (t *Test) Set(i uint64) {
+	t.v = i
+}
+
+func main() {
+	m := task.NewMission()
+	defer m.Done()
+
+	tt := NewTest(0)
+	tt_ref := weak_ref.New(tt)
+
+	defer log.Println("Reset")
+	defer tt_ref.Reset()
+
+	do_ch := make(chan struct{})
+
+	for i := uint64(1); i <= 5; i++ {
+		go func(wm *task.Mission, id uint64) {
+			defer wm.Done()
+
+			cas_tries := 0
+			slow_incr := func(i interface{}) interface{} {
+				tt := i.(*Test)
+
+				cas_tries++
+				time.Sleep(100 * time.Millisecond)
+				return NewTest(tt.Value() + 1)
+			}
+
+			<-do_ch // Ready, go!
+			ref := tt_ref.CasUpdate(slow_incr)
+			if ref == nil {
+				log.Printf("Cancel(id:%d)\n", id)
+				return
+			}
+
+			tt := ref.(*Test)
+			log.Printf("Success(id:%d, tries:%d, value:%+v)\n",
+				id, cas_tries, tt)
+		}(m.New(), i)
+	}
+
+	close(do_ch)
+	time.Sleep(350 * time.Millisecond)
+}

docs/two_ref.png

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"log"
+	"time"
+
+	"github.com/l4go/task"
+	"github.com/l4go/weak_ref"
+)
+
+func main() {
+	m := task.NewMission()
+	defer m.Done()
+
+	var val int = 0
+	w_ref := weak_ref.New(&val)
+
+	defer log.Println("Reset")
+	defer w_ref.Reset()
+
+	do_ch := make(chan struct{})
+
+	for i := uint64(1); i <= 5; i++ {
+		go func(wm *task.Mission, id uint64) {
+			defer wm.Done()
+
+			cas_tries := 0
+			<-do_ch // Ready, go!
+
+		cas_again:
+			o_ref := w_ref.Get()
+			if o_ref == nil {
+				log.Printf("Cancel(id:%d)\n", id)
+				return
+			}
+
+			time.Sleep(100 * time.Millisecond)
+
+			n_val := *(o_ref.(*int)) + 1
+			if !w_ref.CompareAndSwap(o_ref, &n_val) {
+				goto cas_again
+			}
+
+			log.Printf("Success(id:%d, tries:%d, value:%d(%+v))\n",
+				id, cas_tries, n_val, &n_val)
+		}(m.New(), i)
+	}
+
+	close(do_ch)
+	time.Sleep(350 * time.Millisecond)
+}

docs/weak_reference.md

@@ -0,0 +1,53 @@
+package main
+
+import (
+	"log"
+	"sync/atomic"
+
+	"github.com/l4go/task"
+	"github.com/l4go/weak_ref"
+)
+
+type Test struct {
+	v uint64
+}
+
+func NewTest(i uint64) *Test {
+	return &Test{v: i}
+}
+func (t *Test) Value() uint64 {
+	return atomic.LoadUint64(&t.v)
+}
+
+func (t *Test) Set(i uint64) {
+	atomic.StoreUint64(&t.v, i)
+}
+
+func main() {
+	m := task.NewMission()
+	defer m.Done()
+
+	tt := NewTest(0)
+	tt_ref := weak_ref.New(tt)
+	defer tt_ref.Reset()
+
+	go free_worker(m.New(), tt_ref.Move())
+
+	if tt_ref.Get() == nil {
+		log.Println("No cleaning required.")
+		return
+	}
+	log.Println("Cleaning.")
+}
+
+func free_worker(wm *task.Mission, tt_ref *weak_ref.WeakRef) {
+	defer wm.Done()
+	defer tt_ref.Reset()
+
+	ref := tt_ref.Get()
+	if ref == nil {
+		log.Println("Fail worker")
+		return
+	}
+	log.Println("Success worker")
+}