Adds some example

Author: ziccardi

examples/routine_leak/example1_no_async_routine_manager/without_async_routine_manager.go

@@ -0,0 +1,57 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"github.com/openshift-online/async-routine/opid"
+	"log/slog"
+	"os"
+	"runtime/pprof"
+	"time"
+)
+
+func main() {
+	slog.Info("Program started")
+
+	for i := 0; i < 10; i++ {
+		foo(opid.NewContext())
+	}
+
+	// Wait enough time to have some routine started
+	time.Sleep(4 * time.Second)
+
+	pprof.Lookup("goroutine").WriteTo(os.Stdout, 1)
+	fmt.Scanln()
+}
+
+func foo(ctx context.Context) {
+	slog.Info("foo() started",
+		"opid", opid.FromContext(ctx))
+	bar(ctx)
+	slog.Info("foo() ended",
+		"opid", opid.FromContext(ctx))
+}
+
+func bar(ctx context.Context) {
+	slog.Info("bar() started",
+		"opid", opid.FromContext(ctx))
+	go parentGoroutine(ctx)
+	slog.Info("bar() ended",
+		"opid", opid.FromContext(ctx))
+}
+
+func parentGoroutine(ctx context.Context) {
+	slog.Info("parentGoroutine() started",
+		"opid", opid.FromContext(ctx))
+
+	go stuckInSelect()
+	time.Sleep(500 * time.Millisecond)
+	slog.Info("parentGoroutine() ended",
+		"opid", opid.FromContext(ctx))
+}
+
+func stuckInSelect() {
+	slog.Info("stuckInSelect() started")
+	select {}
+	slog.Info("stuckInSelect() ended")
+}

examples/routine_leak/example1_with_async_routine_manager/with_async_routine_manager.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"context"
+	"github.com/openshift-online/async-routine"
+	"github.com/openshift-online/async-routine/opid"
+	"log/slog"
+	"time"
+)
+
+var _ async.RoutinesObserver = (*exampleRoutineObserver)(nil)
+
+func main() {
+	slog.Info("Program started")
+
+	// Setup the AsyncRoutineManager
+	async.Manager(
+		// Take a snapshot every 2 seconds
+		async.WithSnapshottingInterval(2 * time.Second)).
+		// Start the routine monitor
+		Monitor().Start()
+
+	// Add our custom observer to the list of routine observers
+	_ = async.Manager().AddObserver(&exampleRoutineObserver{})
+
+	for i := 0; i < 10; i++ {
+		foo(opid.NewContext())
+	}
+
+	// Wait enough time to have some routine started
+	time.Sleep(4 * time.Second)
+}
+
+func foo(ctx context.Context) {
+	slog.Info("foo() started",
+		"opid", opid.FromContext(ctx))
+	bar(ctx)
+	slog.Info("foo() ended",
+		"opid", opid.FromContext(ctx))
+}
+
+func bar(ctx context.Context) {
+	slog.Info("bar() started",
+		"opid", opid.FromContext(ctx))
+	async.NewAsyncRoutine("parent go routine", ctx,
+		func() {
+			parentGoroutine(ctx)
+		}).
+		Timebox(2 * time.Second).
+		Run()
+	slog.Info("bar() ended",
+		"opid", opid.FromContext(ctx))
+}
+
+func parentGoroutine(ctx context.Context) {
+	slog.Info("parentGoroutine() started",
+		"opid", opid.FromContext(ctx))
+
+	async.NewAsyncRoutine("stuck in select", ctx, stuckInSelect).
+		Timebox(2 * time.Second).
+		Run()
+	time.Sleep(500 * time.Millisecond)
+
+	slog.Info("parentGoroutine() ended",
+		"opid", opid.FromContext(ctx))
+}
+
+func stuckInSelect() {
+	slog.Info("parentGoroutine() started")
+	select {}
+	slog.Info("parentGoroutine() ended")
+}
+
+type exampleRoutineObserver struct{}
+
+func (e exampleRoutineObserver) RoutineStarted(routine async.AsyncRoutine) {
+	slog.Info("Routine started",
+		"name", routine.Name(),
+		"opid", routine.OpId(),
+		"parent-opid", routine.OriginatorOpId(),
+	)
+}
+
+func (e exampleRoutineObserver) RoutineFinished(routine async.AsyncRoutine) {
+	slog.Info("Routine finished",
+		"name", routine.Name(),
+		"opid", routine.OpId(),
+		"parent-opid", routine.OriginatorOpId(),
+	)
+}
+
+func (e exampleRoutineObserver) RoutineExceededTimebox(routine async.AsyncRoutine) {
+	slog.Warn("Routine exceeded timebox",
+		"name", routine.Name(),
+		"opid", routine.OpId(),
+		"parent-opid", routine.OriginatorOpId(),
+		"startedAt", routine.StartedAt(),
+	)
+}
+
+func (e exampleRoutineObserver) RunningRoutineCount(count int) {
+	// nothing to do in this example
+}
+
+func (e exampleRoutineObserver) RunningRoutineByNameCount(name string, count int) {
+	// nothing to do in this example
+}

examples/routine_leak/example2/README.md

@@ -0,0 +1,13 @@
+# Routine Leak Detection with AsyncRoutineManager
+This demonstration illustrates how the `AsyncRoutineManager` help identifying routine leaks and pinpoint their source.
+
+Each folder, named step1 to stepN, adds a progressive integration of the `AsyncRoutineManager`, starting from the 
+naked code of `step1` to the full integration in the last step.
+
+The application we are going to use for this demonstration is very simple:
+
+1. The `main` function starts the `doJob` go routine and then, every 4 seconds, prints the `pproof` goroutine dump
+2. `doJob` runs indefinitely and every 50 milliseconds invokes the `foo` function
+3. `foo` just invokes `bar` wich in turn starts the `parentGoRoutine` routine
+4. `parentGoRoutine` starts the `doInterestingStuff` routine passing a random number between 0 and 99
+5. `doInterestingStuff` hangs indefinitely if the received value is a multiple of 4, otherwise exits

examples/routine_leak/example2/step1/README.md

@@ -0,0 +1,24 @@
+# STEP1 - the leaking code
+
+In this step, we will use the native `go` keyword to start go routines.
+The code is very simple:
+
+1. The `main` function starts the `doJob` go routine and then, every 4 seconds, prints the `pproof` goroutine dump
+2. `doJob` runs indefinitely and every 50 milliseconds invokes the `foo` function
+3. `foo` just invokes `bar` wich in turn starts the `parentGoRoutine` routine
+4. `parentGoRoutine` starts the `doInterestingStuff` routine passing a random number between 0 and 99
+5. `doInterestingStuff` hangs indefinitely if the received value is a multiple of 4, otherwise exits
+
+Running the application we can see how the total number of goroutine keeps increasing:
+```
+goroutine profile: total 32
+20 @ 0x100e9caa8 0x100e7d520 0x100ef588c 0x100ea42b4
+#	0x100ef588b	main.doInterestingStuff+0x3b
+...
+...
+goroutine profile: total 50
+38 @ 0x100e9caa8 0x100e7d520 0x100ef588c 0x100ea42b4
+#	0x100ef588b	main.doInterestingStuff+0x3b
+```
+
+We can see that the leaked routine os the `doInterestingStuff` but we have no idea of the context of execution.

examples/routine_leak/example2/step1/app_leaking_routine.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"math/rand"
+	"os"
+	"runtime/pprof"
+	"time"
+)
+
+func main() {
+	go doJob()
+
+	for {
+		time.Sleep(4 * time.Second)
+		_ = pprof.Lookup("goroutine").WriteTo(os.Stdout, 1)
+	}
+
+}
+
+func doJob() {
+	for {
+		foo()
+		time.Sleep(50 * time.Millisecond)
+	}
+}
+
+func foo() {
+	bar()
+}
+
+func bar() {
+	go parentGoroutine()
+}
+
+func parentGoroutine() {
+	go doInterestingStuff(rand.Intn(100))
+	time.Sleep(500 * time.Millisecond)
+}
+
+func doInterestingStuff(value int) {
+	if value%4 == 0 {
+		select {}
+	}
+}

examples/routine_leak/example2/step2/README.md

@@ -0,0 +1,7 @@
+# STEP2 - integrating the AsyncRoutineManager
+
+In this step, we integrate the `AsyncRoutineManager` to handle routine management.
+In fact, incorporating the `AsyncRoutineManager` is almost as simple as replacing the `go` keyword with a call
+to the `NewAsyncRoutine` function.
+Running this code produces the same behavior as in STEP 1, but now we have established the foundation to 
+fully leverage the capabilities of the `AsyncRoutineManager`.

examples/routine_leak/example2/step2/app_leaking_routine.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"context"
+	"github.com/openshift-online/async-routine"
+	"math/rand"
+	"os"
+	"runtime/pprof"
+	"time"
+)
+
+func main() {
+	async.
+		NewAsyncRoutine("main-job", context.Background(), doJob).
+		Run()
+
+	for {
+		time.Sleep(4 * time.Second)
+		_ = pprof.Lookup("goroutine").WriteTo(os.Stdout, 1)
+	}
+
+}
+
+func doJob() {
+	for {
+		foo()
+		time.Sleep(50 * time.Millisecond)
+	}
+}
+
+func foo() {
+	bar()
+}
+
+func bar() {
+	async.
+		NewAsyncRoutine("parent-go-routine", context.Background(), parentGoroutine).
+		Run()
+}
+
+func parentGoroutine() {
+	async.
+		NewAsyncRoutine("run-command", context.Background(), func() { doInterestingStuff(rand.Intn(100)) }).
+		Run()
+	time.Sleep(500 * time.Millisecond)
+}
+
+func doInterestingStuff(value int) {
+	if value%4 == 0 {
+		select {}
+	}
+}

examples/routine_leak/example2/step3/README.md

@@ -0,0 +1,40 @@
+# STEP3 - Replacing the pproof dump with a Routine Observer
+
+In this example, we implement an observer that prints the number of running routine:
+```go
+
+type leakingRoutineObserver struct{}
+
+func (l leakingRoutineObserver) RunningRoutineCount(count int) {
+	fmt.Println("running routine count:", count)
+}
+...
+...
+```
+
+Next, to ensure the observer is automatically notified of all running routines, we need to register the 
+observer and start the monitor.
+
+```go
+func main() {
+    async.Manager(async.WithSnapshottingInterval(500 * time.Millisecond)).Monitor().Start()
+    async.Manager().AddObserver(&leakingRoutineObserver{})
+	...
+	...
+}
+```
+
+The output will be something like this: 
+```
+running routine count: 14
+running routine count: 17
+running routine count: 19
+running routine count: 21
+running routine count: 23
+running routine count: 28
+running routine count: 30
+running routine count: 31
+...
+```
+
+We can see we have a routine leak, but we still have no idea of what is the routine leak.