add example context/cancel3

Author: MichalAdorno

README.md

@@ -1,8 +1,13 @@
 # Notes: Golang Advanced Concurrency Concepts
 
 The tutorial consist of the following modules (in sense of Go Modules):
-* `context/server`
-* `context/cancellation`
+* `context/cancel1`
+* `context/cancel2`
+* `context/cancel3`
+* `context/emit`
+* `context/listen`
+* `context/timeout`
+* `context/value`
 * `error_group`
 * `errors_in_waitgroup`
 * `gosched`
@@ -23,6 +28,34 @@ There are two sides to the context cancellation, that can be implemented:
 * Listening for the cancellation event, 
 * Emitting the cancellation event.
 
+Things to remember about `context`:
+* A `context` object can be cancelled only once
+* Use it when you want to actually cancell an operation, not when you want to propagate errors
+* Wrapping a cancellable context with `WithTimeout` or other functions make the context object cancellable in too many ways.
+* Pass a child context to a goroutine you start or pass an independent context object. Here is an example:
+```
+func parent(rootCtx context.Context) {
+	ctx, cancel := context.WithCancel(rootCtx)
+	defer cancel()
+
+	someArg := "loremipsum"
+	go child(context.Background(), someArg)
+}
+```
+Note: calling `cancel()` in the parent goroutine may cancel the child goroutine because there is no synchronization of the child - `parent()` (and thus its `defer`) does not wait for `child()`.
+* do not pass the `cancel()` function downstream. It will result in the invoker of the cancellation function not knowning what the upstream impact of cancelling the context may be eg. there may be other contexts that are derived from the cancelled context.
+
+
+Context factory methods:
+* for a parent/new context: `Background()`
+* for a cancellation context:  `WithCancel()`
+* for a time-limited context: `WithTimeout()`, `WithDeadline()`
+* for a key-value storing context: `WithValue()`
+* for an empty context:`TODO()`.
+
+How to accept/use `context` objects in downstream:
+
+
 
 ### `context/listen`
 In this example an HTTP server on port 9000 is set up. It processes a request within 2 seconds.

context/cancel1/go.mod

@@ -0,0 +1,3 @@
+module cancel1
+
+go 1.14

context/cancel1/main.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"time"
+)
+
+/*
+	The program shows how to use context cancellation in a sub-task.
+	However it contains a logical error worth considering:
+	You cannot call `cancel()` twice,
+	therfore you cannot use the same context object to cancel multiple goroutines.
+*/
+func main() {
+	ctx := context.Background()
+	ctx, cancel := context.WithCancel(ctx)
+	go foo(ctx, "subtask-1")
+	go foo(ctx, "subtask-2") //note: one of the goroutines will not be cancelled, the main routine will just cause it to end!
+	time.Sleep(100 * time.Millisecond)
+	cancel() //note: calling `cancel()` more than once does not yield any results.
+	//cancel()
+	fmt.Println("Back to the main routine")
+}
+
+func foo(ctx context.Context, str string) {
+	fmt.Printf("Entering foo() with message: [%s]\n", str)
+	select {
+	case <-time.After(500 * time.Millisecond):
+		fmt.Printf("Executing foo() with message: [%s]\n", str)
+	case <-ctx.Done():
+		fmt.Printf("Cancelling foo() with message: [%s]\n", str)
+		return
+	}
+	fmt.Printf("Finishing foo() with message: [%s]\n", str)
+}

context/cancel3/go.mod

@@ -0,0 +1,3 @@
+module cancel3
+
+go 1.14

context/cancel3/main.go

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"context"
+	"fmt"
+)
+
+/*
+	See godoc: https://golang.org/pkg/context/#WithCancel
+*/
+func main() {
+	ctx, cancel := context.WithCancel(context.Background())
+
+	for n := range yield(1, ctx) {
+		fmt.Println(n)
+		if n == 5 { //We want to consume only this number of elements from the channel
+			// (1)
+			//break
+			// cancel()
+			break
+		}
+	}
+
+	// (2)
+	cancel() //or alternatively: defer cancel() // cancel when we are finished consuming integers
+}
+
+/*
+	`yield` generates integers in a separate goroutine and
+	sends them to the returned channel.
+	The callers of gen need to cancel the context once
+	they are done consuming generated integers not to
+	leak the internal goroutine started by gen.
+*/
+func yield(start int, ctx context.Context) <-chan int {
+	dst := make(chan int)
+	n := start
+	go func() {
+		for {
+			select {
+			case <-ctx.Done():
+				// (3)
+				// close(dst)
+				return // returning not to leak the goroutine
+			case dst <- n:
+				n++
+			}
+		}
+	}()
+	return dst
+}

context/timeout/go.mod

@@ -0,0 +1,3 @@
+module timeout
+
+go 1.14

context/timeout/main.go

@@ -8,24 +8,25 @@ import (
 )
 
 func main() {
-	// Create a new context
-	// With a deadline of 100 milliseconds
+	/*
+		Create a new context with a deadline of 100 milliseconds.
+		If 100 ms -> most likely you will get a timeout error passed through the context.
+		If eg 500 ms -> most likely you will get 200 OK and no context cancellation.
+	*/
 	ctx := context.Background()
 	ctx, _ = context.WithTimeout(ctx, 100*time.Millisecond)
 
-	// Make a request, that will call the google homepage
+	// Make a request, that will call some HTTP server
 	req, _ := http.NewRequest(http.MethodGet, "http://google.com", nil)
 	// Associate the cancellable context we just created to the request
 	req = req.WithContext(ctx)
-
 	// Create a new HTTP client and execute the request
-	client := &http.Client{}
-	res, err := client.Do(req)
-	// If the request failed, log to STDOUT
+	res, err := (&http.Client{}).Do(req)
+	// If the request failed, log to the standard output
 	if err != nil {
-		fmt.Println("Request failed:", err)
+		fmt.Println("Request failed:", err) //`err` contains the info about time limit excess
 		return
 	}
 	// Print the statuscode if the request succeeds
-	fmt.Println("Response received, status code:", res.StatusCode)
+	fmt.Println("Response received with status code:", res.StatusCode)
 }