0
# Arrow FX Coroutines
1

2
Arrow FX Coroutines is a comprehensive Kotlin library that provides functional effect types and utilities for managing side effects in Kotlin coroutines. It offers structured concurrency patterns, resource management, parallel processing capabilities, and advanced synchronization primitives designed around functional programming principles.
3

4
## Package Information
5

6
- **Package Name**: arrow-fx-coroutines
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("io.arrow-kt:arrow-fx-coroutines:2.2.0-beta.3")`
10

11
## Core Imports
12

13
```kotlin
14
import arrow.fx.coroutines.*
15
```
16

17
For specific functionality:
18

19
```kotlin
20
import arrow.fx.coroutines.Resource
21
import arrow.fx.coroutines.parZip
22
import arrow.fx.coroutines.resourceScope
23
```
24

25
## Basic Usage
26

27
```kotlin
28
import arrow.fx.coroutines.*
29

30
suspend fun main() {
31
    // Resource management with automatic cleanup
32
    resourceScope {
33
        val file = resource({ openFile() }, { it.close() }).bind()
34
        val connection = resource({ openConnection() }, { it.close() }).bind()
35
        
36
        // Use resources safely - cleanup guaranteed
37
        processData(file, connection)
38
    }
39
    
40
    // Parallel execution
41
    val result = parZip(
42
        { fetchUserData() },
43
        { fetchSettings() }
44
    ) { userData, settings ->
45
        combineData(userData, settings)
46
    }
47
    
48
    // Racing operations
49
    val winner = raceN(
50
        { slowOperation() },
51
        { fastOperation() }
52
    )
53
}
54
```
55

56
## Architecture
57

58
Arrow FX Coroutines is built around several key concepts:
59

60
- **Structured Concurrency**: All operations respect cancellation and provide proper cleanup
61
- **Resource Safety**: Automatic resource management with guaranteed cleanup
62
- **Functional Patterns**: Higher-order functions and composition for building complex operations
63
- **Type Safety**: Full Kotlin type system integration with proper error handling
64

65
## Capabilities
66

67
### Resource Management
68

69
Comprehensive resource management with automatic cleanup and proper exception handling.
70

71
```kotlin { .api }
72
suspend fun <A> resourceScope(action: suspend ResourceScope.() -> A): A
73
fun <A> resource(block: suspend ResourceScope.() -> A): Resource<A>
74
fun <A> resource(acquire: suspend () -> A, release: suspend (A, ExitCase) -> Unit): Resource<A>
75
suspend fun <A, B> Resource<A>.use(f: suspend (A) -> B): B
76
typealias Resource<A> = suspend ResourceScope.() -> A
77
```
78

79
For detailed resource management patterns, lifecycle control, and advanced resource composition, see [Resource Management](./resource-management.md).
80

81
### Parallel Processing
82

83
High-performance parallel execution with concurrency control and error accumulation.
84

85
```kotlin { .api }
86
suspend fun <A, B> Iterable<A>.parMap(context: CoroutineContext = EmptyCoroutineContext, concurrency: Int, f: suspend CoroutineScope.(A) -> B): List<B>
87
suspend fun <A, B> Iterable<A>.parMap(context: CoroutineContext = EmptyCoroutineContext, transform: suspend CoroutineScope.(A) -> B): List<B>
88
suspend fun <A, B, C> parZip(crossinline fa: suspend CoroutineScope.() -> A, crossinline fb: suspend CoroutineScope.() -> B, crossinline f: suspend CoroutineScope.(A, B) -> C): C
89
suspend fun <A, B, C> parZip(ctx: CoroutineContext = EmptyCoroutineContext, crossinline fa: suspend CoroutineScope.() -> A, crossinline fb: suspend CoroutineScope.() -> B, crossinline f: suspend CoroutineScope.(A, B) -> C): C
90
```
91

92
For parallel mapping, zipping operations, and error handling strategies, see [Parallel Processing](./parallel-processing.md).
93

94
### Racing and Competition
95

96
Competitive execution patterns where multiple operations race to completion.
97

98
```kotlin { .api }
99
suspend fun <A, B> raceN(crossinline fa: suspend CoroutineScope.() -> A, crossinline fb: suspend CoroutineScope.() -> B): Either<A, B>
100
suspend fun <A, B> raceN(ctx: CoroutineContext = EmptyCoroutineContext, crossinline fa: suspend CoroutineScope.() -> A, crossinline fb: suspend CoroutineScope.() -> B): Either<A, B>
101
suspend fun <A> racing(block: RacingScope<A>.() -> Unit): A
102
```
103

104
For racing operations, timeout handling, and competitive execution patterns, see [Racing Operations](./racing.md).
105

106
### Structured Error Handling
107

108
Integration with Arrow's Raise system for functional error handling and accumulation.
109

110
```kotlin { .api }
111
suspend fun <Error, A, B> Iterable<A>.parMapOrAccumulate(context: CoroutineContext = EmptyCoroutineContext, transform: suspend ScopedRaiseAccumulate<Error>.(A) -> B): Either<NonEmptyList<Error>, List<B>>
112
suspend fun <E, A, B, C> Raise<NonEmptyList<E>>.parZipOrAccumulate(crossinline fa: suspend ScopedRaiseAccumulate<E>.() -> A, crossinline fb: suspend ScopedRaiseAccumulate<E>.() -> B, crossinline transform: suspend CoroutineScope.(A, B) -> C): C
113
```
114

115
For error accumulation, structured error handling, and integration with Arrow's type system, see [Error Handling](./error-handling.md).
116

117
### Synchronization and Flow Processing
118

119
Advanced synchronization primitives and Flow extensions for concurrent coordination.
120

121
```kotlin { .api }
122
class CountDownLatch(initial: Long) {
123
    fun count(): Long
124
    suspend fun await()
125
    fun countDown()
126
}
127
class CyclicBarrier(capacity: Int, barrierAction: () -> Unit = {}) {
128
    val capacity: Int
129
    suspend fun await()
130
    suspend fun reset()
131
}
132
suspend fun <A, B> Flow<A>.parMap(concurrency: Int = DEFAULT_CONCURRENCY, crossinline transform: suspend CoroutineScope.(A) -> B): Flow<B>
133
```
134

135
For synchronization primitives, Flow extensions, and timing utilities, see [Synchronization and Flow](./synchronization-flow.md).
136

137
### Bracket Pattern and Resource Safety
138

139
Fundamental bracket patterns for safe resource acquisition and guaranteed cleanup.
140

141
```kotlin { .api }
142
suspend fun <A, B> bracket(crossinline acquire: suspend () -> A, use: suspend (A) -> B, crossinline release: suspend (A) -> Unit): B
143
suspend fun <A, B> bracketCase(crossinline acquire: suspend () -> A, use: suspend (A) -> B, crossinline release: suspend (A, ExitCase) -> Unit): B
144
suspend fun <A> guarantee(fa: suspend () -> A, crossinline finalizer: suspend () -> Unit): A
145
suspend fun <A> guaranteeCase(fa: suspend () -> A, crossinline finalizer: suspend (ExitCase) -> Unit): A
146
suspend fun <A> onCancel(fa: suspend () -> A, crossinline onCancel: suspend () -> Unit): A
147
```
148

149
For fundamental resource safety patterns and bracket operations, see [Resource Management](./resource-management.md).
150

151
## Types
152

153
```kotlin { .api }
154
sealed class ExitCase {
155
    object Completed : ExitCase
156
    data class Cancelled(val exception: CancellationException) : ExitCase
157
    data class Failure(val failure: Throwable) : ExitCase
158
    companion object {
159
        fun ExitCase(error: Throwable): ExitCase
160
    }
161
}
162
```
163

164
## Exception Handling
165

166
All operations in Arrow FX Coroutines properly handle cancellation and exceptions:
167

168
- **Cancellation Safety**: All operations can be safely cancelled without resource leaks
169
- **Exception Propagation**: Exceptions are properly propagated through the structured concurrency hierarchy
170
- **Resource Cleanup**: Resources are always cleaned up, even in the presence of exceptions or cancellation
171

172
## Performance Considerations
173

174
- **Structured Concurrency**: Built on Kotlin's structured concurrency for optimal performance
175
- **Concurrency Control**: Configurable concurrency limits prevent resource exhaustion
176
- **Resource Pooling**: Efficient resource management with minimal overhead
177
- **Type Safety**: Zero-cost abstractions that compile to efficient bytecode