or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-handling.mdindex.mdparallel-processing.mdracing.mdresource-management.mdsynchronization-flow.md
tile.json

tessl/maven-io-arrow-kt--arrow-fx-coroutines-jvm

Arrow Fx Coroutines provides functional effect types and utilities for managing side effects in Kotlin coroutines

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.arrow-kt/arrow-fx-coroutines@2.2.x

To install, run

npx @tessl/cli install tessl/maven-io-arrow-kt--arrow-fx-coroutines-jvm@2.2.0

index.mddocs/

Arrow FX Coroutines

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.

Package Information

  • Package Name: arrow-fx-coroutines
  • Package Type: maven
  • Language: Kotlin
  • Installation: implementation("io.arrow-kt:arrow-fx-coroutines:2.2.0-beta.3")

Core Imports

import arrow.fx.coroutines.*

For specific functionality:

import arrow.fx.coroutines.Resource
import arrow.fx.coroutines.parZip
import arrow.fx.coroutines.resourceScope

Basic Usage

import arrow.fx.coroutines.*

suspend fun main() {
    // Resource management with automatic cleanup
    resourceScope {
        val file = resource({ openFile() }, { it.close() }).bind()
        val connection = resource({ openConnection() }, { it.close() }).bind()
        
        // Use resources safely - cleanup guaranteed
        processData(file, connection)
    }
    
    // Parallel execution
    val result = parZip(
        { fetchUserData() },
        { fetchSettings() }
    ) { userData, settings ->
        combineData(userData, settings)
    }
    
    // Racing operations
    val winner = raceN(
        { slowOperation() },
        { fastOperation() }
    )
}

Architecture

Arrow FX Coroutines is built around several key concepts:

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

Capabilities

Resource Management

Comprehensive resource management with automatic cleanup and proper exception handling.

suspend fun <A> resourceScope(action: suspend ResourceScope.() -> A): A
fun <A> resource(block: suspend ResourceScope.() -> A): Resource<A>
fun <A> resource(acquire: suspend () -> A, release: suspend (A, ExitCase) -> Unit): Resource<A>
suspend fun <A, B> Resource<A>.use(f: suspend (A) -> B): B
typealias Resource<A> = suspend ResourceScope.() -> A

For detailed resource management patterns, lifecycle control, and advanced resource composition, see Resource Management.

Parallel Processing

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

suspend fun <A, B> Iterable<A>.parMap(context: CoroutineContext = EmptyCoroutineContext, concurrency: Int, f: suspend CoroutineScope.(A) -> B): List<B>
suspend fun <A, B> Iterable<A>.parMap(context: CoroutineContext = EmptyCoroutineContext, transform: suspend CoroutineScope.(A) -> B): List<B>
suspend fun <A, B, C> parZip(crossinline fa: suspend CoroutineScope.() -> A, crossinline fb: suspend CoroutineScope.() -> B, crossinline f: suspend CoroutineScope.(A, B) -> C): C
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

For parallel mapping, zipping operations, and error handling strategies, see Parallel Processing.

Racing and Competition

Competitive execution patterns where multiple operations race to completion.

suspend fun <A, B> raceN(crossinline fa: suspend CoroutineScope.() -> A, crossinline fb: suspend CoroutineScope.() -> B): Either<A, B>
suspend fun <A, B> raceN(ctx: CoroutineContext = EmptyCoroutineContext, crossinline fa: suspend CoroutineScope.() -> A, crossinline fb: suspend CoroutineScope.() -> B): Either<A, B>
suspend fun <A> racing(block: RacingScope<A>.() -> Unit): A

For racing operations, timeout handling, and competitive execution patterns, see Racing Operations.

Structured Error Handling

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

suspend fun <Error, A, B> Iterable<A>.parMapOrAccumulate(context: CoroutineContext = EmptyCoroutineContext, transform: suspend ScopedRaiseAccumulate<Error>.(A) -> B): Either<NonEmptyList<Error>, List<B>>
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

For error accumulation, structured error handling, and integration with Arrow's type system, see Error Handling.

Synchronization and Flow Processing

Advanced synchronization primitives and Flow extensions for concurrent coordination.

class CountDownLatch(initial: Long) {
    fun count(): Long
    suspend fun await()
    fun countDown()
}
class CyclicBarrier(capacity: Int, barrierAction: () -> Unit = {}) {
    val capacity: Int
    suspend fun await()
    suspend fun reset()
}
suspend fun <A, B> Flow<A>.parMap(concurrency: Int = DEFAULT_CONCURRENCY, crossinline transform: suspend CoroutineScope.(A) -> B): Flow<B>

For synchronization primitives, Flow extensions, and timing utilities, see Synchronization and Flow.

Bracket Pattern and Resource Safety

Fundamental bracket patterns for safe resource acquisition and guaranteed cleanup.

suspend fun <A, B> bracket(crossinline acquire: suspend () -> A, use: suspend (A) -> B, crossinline release: suspend (A) -> Unit): B
suspend fun <A, B> bracketCase(crossinline acquire: suspend () -> A, use: suspend (A) -> B, crossinline release: suspend (A, ExitCase) -> Unit): B
suspend fun <A> guarantee(fa: suspend () -> A, crossinline finalizer: suspend () -> Unit): A
suspend fun <A> guaranteeCase(fa: suspend () -> A, crossinline finalizer: suspend (ExitCase) -> Unit): A
suspend fun <A> onCancel(fa: suspend () -> A, crossinline onCancel: suspend () -> Unit): A

For fundamental resource safety patterns and bracket operations, see Resource Management.

Types

sealed class ExitCase {
    object Completed : ExitCase
    data class Cancelled(val exception: CancellationException) : ExitCase
    data class Failure(val failure: Throwable) : ExitCase
    companion object {
        fun ExitCase(error: Throwable): ExitCase
    }
}

Exception Handling

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

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

Performance Considerations

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