Concurrency Summary

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Goroutine 1 │     │ Goroutine 2 │     │ Goroutine 3 │
├─────────────┤     ├─────────────┤     ├─────────────┤
│ Command A   │     │ Command B   │     │ Command C   │
│ (cat.Cat)   │     │ (grep.Grep) │     │ (awk.Awk)   │
├─────────────┤     ├─────────────┤     ├─────────────┤
│ Own Inputs  │     │ Own Inputs  │     │ Own Inputs  │
│ Own Files   │     │ Own Files   │     │ Own Files   │
│ Own State   │     │ Own State   │     │ Own State   │
└─────────────┘     └─────────────┘     └─────────────┘
      ↓                   ↓                   ↓
   file1.txt           file2.txt           file3.txt

❌ This is NOT supported (would break semantic guarantees):
┌──────────────────────────────────────┐
│ Single Command Instance              │
├──────────────────────────────────────┤
│ Lines distributed across workers:    │
│   Worker 1: Line 1, 4, 7             │
│   Worker 2: Line 2, 5, 8             │
│   Worker 3: Line 3, 6, 9             │
└──────────────────────────────────────┘
(Order and line numbers would be wrong)

## Concurrency

### Running Commands Concurrently

Each command instance can run in its own goroutine:

````go
var wg sync.WaitGroup
files := []string{"file1.txt", "file2.txt", "file3.txt"}

for _, file := range files {
    wg.Add(1)
    go func(f string) {
        defer wg.Done()
        yup.Run(cat.Cat(f))
    }(file)
}
wg.Wait()
```text
````

```````text

``````text

#### Important: One Instance, One Execution

⚠️ **Do not reuse command instances across goroutines:**

```go
// ❌ UNSAFE
cmd := cat.Cat("file.txt")
go yup.Run(cmd)
go yup.Run(cmd)  // Same instance used twice

// ✅ SAFE
go yup.Run(cat.Cat("file.txt"))
go yup.Run(cat.Cat("file.txt"))  // New instance each time
```text

#### Output Interleaving

When multiple commands write to the same output stream concurrently, their output may interleave. Use synchronized wrappers if ordered output is required.

````text

### Command Developer Documentation

Add to framework developer docs:

```markdown
### Concurrency Considerations for Command Developers

Commands you implement are automatically goroutine-safe for concurrent
instances, as long as you follow these guidelines:

1. **Don't use package-level variables** for command state
2. **Capture command-specific state** in closures or the command struct
3. **Let each command instance be independent**

Example of safe command implementation:

```go
func (c command) Executor() yup.CommandExecutor {
    return yup.LineTransform(func(line string) (string, bool) {
        // ✅ SAFE: c is captured per command instance
        if strings.Contains(line, string(c.Flags.Pattern)) {
            return line, true
        }
        return "", false
    }).Executor()
}
````text

`````text

## Effort Assessment for Enhanced Concurrency

If you wanted to add **optional** parallel processing within commands:

| Feature | Effort | Value | Recommendation |
|---------|--------|-------|----------------|
| Document current behavior | **Low** | **High** | ✅ **Do This** |
| Add concurrency examples | **Low** | **Medium** | ✅ **Do This** |
| Parallel line helpers | **Medium** | **Low** | ⚠️ Only if requested |
| Synchronized I/O wrappers | **Low** | **Medium** | ⚠️ Nice to have |
| Parallel awk processing | **High** | **Very Low** | ❌ Not recommended |

### Why Not Add Internal Parallelism?

1. **Semantic compatibility**: Unix tools process lines sequentially
2. **I/O bound**: Most text processing is limited by I/O, not CPU
3. **Complexity**: Parallel processing adds significant complexity for minimal gain
4. **Order guarantees**: Line numbers and order matter in many use cases

## Bottom Line

**The framework DOES support goroutines** for the most common and useful pattern:
**running multiple independent commands concurrently**. This is:

- ✅ Safe by design
- ✅ Works today
- ✅ Covers 95% of real-world concurrent use cases
- ✅ Requires no framework changes
- ✅ Just needs documentation

**The framework does NOT support** (and shouldn't):
- ❌ Parallel line processing within a single command
- ⚠️ Shared I/O streams will interleave without synchronization

**Recommended messaging**:
> "Yupsh commands are goroutine-safe. Each command instance runs
> independently and can execute in its own goroutine. This enables
> efficient concurrent processing of multiple files or data streams."

## Files Created

1. **CONCURRENCY_ANALYSIS.md** - Comprehensive technical analysis (this file)
2. **examples/concurrency_demo.go** - Runnable demonstrations of what works and what doesn't
3. **examples/race_test.go** - Tests showing safe and unsafe patterns
4. **examples/race_demo.go** - Standalone race condition demonstration

Run the demo with:
```bash
cd examples
go run concurrency_demo.go
````text

Run race detection with:

```bash
go run -race race_demo.go
```
```````