docs: enhance and refactor package examples

Author: reugn

examples/.gitignore

@@ -1,2 +1,3 @@
 goroutine/goroutine
 future/future
+cyclic_barrier/cyclic_barrier

examples/cyclic_barrier/main.go

@@ -0,0 +1,59 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/reugn/async"
+)
+
+func main() {
+	fmt.Println("=== CyclicBarrier Example ===")
+	barrier := async.NewCyclicBarrier(3)
+	var wg sync.WaitGroup
+
+	for i := 1; i <= 3; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			fmt.Printf("Goroutine %d: starting work\n", id)
+			time.Sleep(time.Duration(id) * 100 * time.Millisecond)
+			fmt.Printf("Goroutine %d: reached barrier\n", id)
+			if err := barrier.Await(); err != nil {
+				fmt.Printf("Goroutine %d: barrier error: %v\n", id, err)
+				return
+			}
+			fmt.Printf("Goroutine %d: passed barrier\n", id)
+		}(i)
+	}
+
+	wg.Wait()
+	fmt.Println("All goroutines completed")
+
+	// Example with context
+	fmt.Println("\n=== CyclicBarrier with Context ===")
+	barrier2 := async.NewCyclicBarrier(2)
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+
+	wg.Add(2)
+
+	go func() {
+		defer wg.Done()
+		time.Sleep(100 * time.Millisecond)
+		if err := barrier2.AwaitContext(ctx); err != nil {
+			fmt.Printf("Goroutine 1: %v\n", err)
+		}
+	}()
+
+	go func() {
+		defer wg.Done()
+		if err := barrier2.AwaitContext(ctx); err != nil {
+			fmt.Printf("Goroutine 2: %v\n", err)
+		}
+	}()
+
+	wg.Wait()
+}

examples/future/main.go

@@ -2,56 +2,128 @@ package main
 
 import (
 	"context"
+	"errors"
+	"fmt"
 	"log"
 	"time"
 
 	"github.com/reugn/async"
+	"github.com/reugn/async/internal/ptr"
 )
 
-const ok = "OK"
-
 func main() {
-	// using a promise
-	future1 := asyncAction()
-	result1, err := future1.Join()
+	runPromiseExample()
+	runTaskExample()
+	runExecutorExample()
+	runTransformationsExample()
+	runRecoveryExample()
+}
+
+func runPromiseExample() {
+	fmt.Println("=== Promise Example ===")
+	future := asyncAction()
+	result, err := future.Join()
 	if err != nil {
 		log.Fatal(err)
 	}
-	log.Print(result1)
+	fmt.Printf("Result: %s\n", result)
+}
 
-	// using a task
-	task := async.NewTask(func() (string, error) { return ok, nil })
-	result2, err := task.Call().Join()
+func runTaskExample() {
+	fmt.Println("\n=== Task Example ===")
+	task := async.NewTask(func() (string, error) {
+		time.Sleep(100 * time.Millisecond)
+		return "Task completed", nil
+	})
+	result, err := task.Call().Join()
 	if err != nil {
 		log.Fatal(err)
 	}
-	log.Print(result2)
+	fmt.Printf("Result: %s\n", result)
+}
 
-	// using the executor
+func runExecutorExample() {
+	fmt.Println("\n=== Executor Example ===")
 	ctx := context.Background()
 	executor := async.NewExecutor[*string](ctx, async.NewExecutorConfig(2, 2))
 
-	future3, err := executor.Submit(func(_ context.Context) (*string, error) {
-		value := ok
-		return &value, nil
+	future, err := executor.Submit(func(_ context.Context) (*string, error) {
+		value := "Executor task completed"
+		return ptr.Of(value), nil
 	})
+	if err != nil {
+		if shutdownErr := executor.Shutdown(); shutdownErr != nil {
+			log.Printf("Error shutting down executor: %v", shutdownErr)
+		}
+		log.Fatal(err)
+	}
+
+	result, err := future.Get(ctx)
+	if err != nil {
+		if shutdownErr := executor.Shutdown(); shutdownErr != nil {
+			log.Printf("Error shutting down executor: %v", shutdownErr)
+		}
+		log.Fatal(err)
+	}
+	fmt.Printf("Result: %s\n", *result)
+
+	if err := executor.Shutdown(); err != nil {
+		log.Printf("Error shutting down executor: %v", err)
+	}
+}
+
+func runTransformationsExample() {
+	fmt.Println("\n=== Future Transformations ===")
+	promise := async.NewPromise[int]()
+	go func() {
+		time.Sleep(50 * time.Millisecond)
+		promise.Success(10)
+	}()
+
+	transformed := promise.Future().
+		Map(func(v int) (int, error) {
+			return v * 2, nil
+		}).
+		FlatMap(func(v int) (async.Future[int], error) {
+			p := async.NewPromise[int]()
+			go func() {
+				time.Sleep(50 * time.Millisecond)
+				p.Success(v + 5)
+			}()
+			return p.Future(), nil
+		})
+
+	result, err := transformed.Join()
 	if err != nil {
 		log.Fatal(err)
 	}
+	fmt.Printf("Transformed result: %d\n", result)
+}
+
+func runRecoveryExample() {
+	fmt.Println("\n=== Error Recovery ===")
+	failingPromise := async.NewPromise[int]()
+	go func() {
+		time.Sleep(50 * time.Millisecond)
+		failingPromise.Failure(errors.New("operation failed"))
+	}()
 
-	result3, err := future3.Get(ctx)
+	recovered := failingPromise.Future().Recover(func() (int, error) {
+		return 10, nil // fallback value
+	})
+
+	result, err := recovered.Join()
 	if err != nil {
 		log.Fatal(err)
 	}
-	log.Print(*result3)
+	fmt.Printf("Recovered result: %d\n", result)
 }
 
 func asyncAction() async.Future[string] {
 	promise := async.NewPromise[string]()
 	go func() {
-		time.Sleep(time.Second)
-		promise.Success(ok)
+		time.Sleep(100 * time.Millisecond)
+		promise.Success("Promise completed")
 	}()
-
 	return promise.Future()
 }

examples/goroutine/main.go

@@ -8,14 +8,21 @@ import (
 )
 
 func main() {
+	fmt.Println("=== Goroutine ID Example ===")
 	var wg sync.WaitGroup
 	wg.Add(5)
+
 	for i := 0; i < 5; i++ {
-		go func() {
-			id, _ := async.GoroutineID()
-			fmt.Println(id)
-			wg.Done()
-		}()
+		go func(id int) {
+			defer wg.Done()
+			goroutineID, err := async.GoroutineID()
+			if err != nil {
+				fmt.Printf("Goroutine %d: failed to get ID: %v\n", id, err)
+				return
+			}
+			fmt.Printf("Goroutine %d: ID = %d\n", id, goroutineID)
+		}(i)
 	}
+
 	wg.Wait()
 }