micro_utils.dokka/dev.inmo.micro_utils.coroutines

Package-level declarations

Types

AccumulatorFlow

class AccumulatorFlow<T>(sourceDataFlow: Flow<T>, scope: CoroutineScope) : AbstractFlow<T>

This Flow will have behaviour very similar to SharedFlow, but there are several differences:

ActorAction

interface ActorAction<T>

ContextSafelyExceptionHandler

class ContextSafelyExceptionHandler(val handler: ExceptionHandler<Unit>) : CoroutineContext.Element

ExceptionHandler wrapper which was created to make possible to use handler across all coroutines calls

ContextSafelyExceptionHandlerKey

object ContextSafelyExceptionHandlerKey : CoroutineContext.Key<ContextSafelyExceptionHandler>

This key can (and will) be used to get ContextSafelyExceptionHandler from coroutineContext of suspend functions and in ContextSafelyExceptionHandler for defining of its CoroutineContext.Element.key

DeferredAction

class DeferredAction<T, O>(val deferred: Deferred<T>, val callback: suspend (T) -> O)

DoWithFirstBuilder

class DoWithFirstBuilder<T>(scope: CoroutineScope)

ExceptionHandler

typealias ExceptionHandler<T> = suspend (Throwable) -> T

FlowOnHierarchyChangeListener

class FlowOnHierarchyChangeListener(recursive: Boolean = false, _onChildViewAdded: MutableSharedFlow<Pair<View, View>> = MutableSharedFlow(extraBufferCapacity = Int.MAX_VALUE), _onChildViewRemoved: MutableSharedFlow<Pair<View, View>> = MutableSharedFlow(extraBufferCapacity = Int.MAX_VALUE)) : ViewGroup.OnHierarchyChangeListener

kotlinx.coroutines.flow.Flow-based android.view.ViewGroup.OnHierarchyChangeListener

SmartMutex

sealed interface SmartMutex

It is interface which will work like classic Mutex, but in difference have lockStateFlow for listening of the SmartMutex state.

SmartRWLocker

class SmartRWLocker(readPermits: Int = Int.MAX_VALUE, writeIsLocked: Boolean = false)

Composite mutex which works with next rules:

SmartSemaphore

sealed interface SmartSemaphore

It is interface which will work like classic Semaphore, but in difference have permitsStateFlow for listening of the SmartSemaphore state.

SpecialMutableStateFlow

open class SpecialMutableStateFlow<T>(initialValue: T) : MutableStateFlow<T> , FlowCollector<T> , MutableSharedFlow<T>

Works like StateFlow, but guarantee that latest value update will always be delivered to each active subscriber

Properties

asDeferred

val <T> T.asDeferred: Deferred<T>

Default

val Default: CoroutineDispatcher

defaultSafelyExceptionHandler

var defaultSafelyExceptionHandler: ExceptionHandler<Nothing>

This instance will be used in all calls of safely where exception handler has not been passed

defaultSafelyWithoutExceptionHandler

var defaultSafelyWithoutExceptionHandler: ExceptionHandler<Unit>

This instance will be used in all calls of safelyWithoutExceptions as an exception handler for safely call

defaultSafelyWithoutExceptionHandlerWithNull

val defaultSafelyWithoutExceptionHandlerWithNull: ExceptionHandler<Nothing?>

Use this handler in cases you wish to include handling of exceptions by defaultSafelyWithoutExceptionHandler and returning null at one time

val IO: CoroutineDispatcher

val UI: MainCoroutineDispatcher

Functions

accumulatorFlow

fun <T> Channel<T>.accumulatorFlow(scope: CoroutineScope): Flow<T>

Creates AccumulatorFlow using this with receiveAsFlow to get

fun <T> Flow<T>.accumulatorFlow(scope: CoroutineScope): Flow<T>

Creates AccumulatorFlow using this as base Flow

actor

fun <T> CoroutineScope.actor(channelCapacity: Int = Channel.UNLIMITED, block: suspend (T) -> Unit): Channel<T>

actorAsync

fun <T> CoroutineScope.actorAsync(channelCapacity: Int = Channel.UNLIMITED, markerFactory: suspend (T) -> Any? = { null }, block: suspend (T) -> Unit): Channel<T>

asyncSafely

fun <T> CoroutineScope.asyncSafely(context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, onException: ExceptionHandler<T> = defaultSafelyExceptionHandler, block: suspend CoroutineScope.() -> T): Deferred<T>

asyncSafelyWithoutExceptions

fun <T> CoroutineScope.asyncSafelyWithoutExceptions(context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, onException: ExceptionHandler<T?> = defaultSafelyWithoutExceptionHandlerWithNull, block: suspend CoroutineScope.() -> T): Deferred<T?>

asyncWeak

fun <T> CoroutineScope.asyncWeak(context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, block: suspend CoroutineScope.() -> T): Deferred<T>

this will be used as base for WeakScope. Other parameters (context, start, block) will be used to create async

awaitFirst

suspend fun <T> Iterable<Deferred<T>>.awaitFirst(cancelOthers: Boolean = true): T

suspend fun <T> Iterable<Deferred<T>>.awaitFirst(scope: CoroutineScope, cancelOnResult: Boolean = true): T

awaitFirstWithDeferred

suspend fun <T> Iterable<Deferred<T>>.awaitFirstWithDeferred(scope: CoroutineScope, cancelOnResult: Boolean = true): Pair<Deferred<T>, T>

buildAction

fun <T, O> Deferred<T>.buildAction(callback: suspend (T) -> O): DeferredAction<T, O>

contextSafelyExceptionHandler

suspend fun contextSafelyExceptionHandler(): ContextSafelyExceptionHandler?

CoroutineScope

fun CoroutineScope(context: CoroutineContext, defaultExceptionsHandler: ExceptionHandler<Unit>): CoroutineScope

createActionsActor

fun CoroutineScope.createActionsActor(): Channel<suspend () -> Unit>

Planned to use with doWithSuspending. Will execute incoming lambdas sequentially

createSafeActionsActor

inline fun CoroutineScope.createSafeActionsActor(noinline onException: ExceptionHandler<Unit> = defaultSafelyExceptionHandler): Channel<suspend () -> Unit>

Planned to use with doWithSuspending. Will execute incoming lambdas sequentially

doIn

inline suspend fun <T> doIn(context: CoroutineContext, noinline block: suspend CoroutineScope.() -> T): T

doInDefault

inline suspend fun <T> doInDefault(noinline block: suspend CoroutineScope.() -> T): T

doInIO

inline suspend fun <T> doInIO(noinline block: suspend CoroutineScope.() -> T): T

doInUI

inline suspend fun <T> doInUI(noinline block: suspend CoroutineScope.() -> T): T

doOutsideOfCoroutine

suspend fun <T> doOutsideOfCoroutine(block: () -> T): T

Call this method in case you need to do something in common thread (like reading of file in JVM)

doSynchronously

fun <T> doSynchronously(block: suspend CoroutineScope.() -> T): T

doSynchronously

fun <T> CoroutineScope.doSynchronously(block: suspend CoroutineScope.() -> T): T

doWithSuspending

suspend fun <T> Channel<suspend () -> Unit>.doWithSuspending(action: ActorAction<T>): T

Must be use with actor created by createActionsActor or createSafeActionsActor. Will send lambda which will execute action and return result.

filterNotNull

fun <T> Flow<T>.filterNotNull(): Flow<T & Any>

first

suspend fun <T> List<Deferred<T>>.first(scope: CoroutineScope, cancelOnResult: Boolean = true): T

firstNotNull

suspend fun <T> Flow<T?>.firstNotNull(): T

firstOf

suspend fun <T> CoroutineScope.firstOf(vararg variants: Deferred<T>, cancelOnResult: Boolean = true): T

suspend fun <T> CoroutineScope.firstOf(cancelOnResult: Boolean = true, block: DoWithFirstBuilder<T>.() -> Unit): T

suspend fun <T> CoroutineScope.firstOf(variants: Iterable<Deferred<T>>, cancelOnResult: Boolean = true): T

flatMap

@JvmName(name = "flatMapIterable")

inline fun <T, R> Flow<Iterable<T>>.flatMap(crossinline mapper: suspend (T) -> R): Flow<R>

inline fun <T, R> Flow<Flow<T>>.flatMap(crossinline mapper: suspend (T) -> R): Flow<R>

flatMapNotNull

@JvmName(name = "flatMapNotNullIterable")

inline fun <T, R> Flow<Iterable<T>>.flatMapNotNull(crossinline mapper: suspend (T) -> R): Flow<R & Any>

inline fun <T, R> Flow<Flow<T>>.flatMapNotNull(crossinline mapper: suspend (T) -> R): Flow<R & Any>

flatten

@JvmName(name = "flattenIterable")

fun <T> Flow<Iterable<T>>.flatten(): Flow<T>

fun <T> Flow<Flow<T>>.flatten(): Flow<T>

invoke

inline suspend operator fun <T> FlowCollector<T>.invoke(value: T)

invokeFirstOf

suspend fun <O> invokeFirstOf(scope: CoroutineScope, vararg variants: DeferredAction<*, O>, cancelOnResult: Boolean = true): O

invokeFirstOf

suspend fun <O> Iterable<DeferredAction<*, O>>.invokeFirstOf(scope: CoroutineScope, cancelOnResult: Boolean = true): O

invokeOnFirst

suspend fun <T, O> invokeOnFirst(scope: CoroutineScope, vararg variants: Deferred<T>, cancelOnResult: Boolean = true, callback: suspend (T) -> O): O

invokeOnFirst

suspend fun <T, O> Iterable<Deferred<T>>.invokeOnFirst(scope: CoroutineScope, cancelOnResult: Boolean = true, callback: suspend (T) -> O): O

invokeOnFirstOf

suspend fun <T, O> CoroutineScope.invokeOnFirstOf(cancelOnResult: Boolean = true, block: DoWithFirstBuilder<T>.() -> Unit, callback: suspend (T) -> O): O

launchInCurrentThread

fun <T> launchInCurrentThread(block: suspend CoroutineScope.() -> T): T

launchSafely

fun CoroutineScope.launchSafely(context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, onException: ExceptionHandler<Unit> = defaultSafelyExceptionHandler, block: suspend CoroutineScope.() -> Unit): Job

launchSafelyWithoutExceptions

fun CoroutineScope.launchSafelyWithoutExceptions(context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, onException: ExceptionHandler<Unit?> = defaultSafelyWithoutExceptionHandlerWithNull, block: suspend CoroutineScope.() -> Unit): Job

launchSynchronously

fun <T> launchSynchronously(block: suspend CoroutineScope.() -> T): T

launchSynchronously

fun <T> CoroutineScope.launchSynchronously(block: suspend CoroutineScope.() -> T): T

launchWeak

fun CoroutineScope.launchWeak(context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, block: suspend CoroutineScope.() -> Unit): Job

this will be used as base for WeakScope. Other parameters (context, start, block) will be used to launch

LinkedSupervisorJob

fun CoroutineContext.LinkedSupervisorJob(additionalContext: CoroutineContext? = null): CoroutineContext

fun CoroutineScope.LinkedSupervisorJob(additionalContext: CoroutineContext? = null): CoroutineContext

LinkedSupervisorScope

fun CoroutineScope.LinkedSupervisorScope(additionalContext: CoroutineContext? = null): CoroutineScope

plus

inline operator fun <T> Flow<T>.plus(other: Flow<T>): Flow<T>

preloadImage

suspend fun preloadImage(src: String): Image

runCatchingSafely

suspend fun <T> runCatchingSafely(onException: ExceptionHandler<T> = defaultSafelyExceptionHandler, block: suspend CoroutineScope.() -> T): Result<T>

runCatchingSafely

suspend fun <T, R> T.runCatchingSafely(onException: ExceptionHandler<R> = defaultSafelyExceptionHandler, block: suspend T.() -> R): Result<R>

runCatchingSafelyWithoutExceptions

suspend fun <T> runCatchingSafelyWithoutExceptions(onException: ExceptionHandler<T?> = defaultSafelyWithoutExceptionHandlerWithNull, block: suspend CoroutineScope.() -> T): Result<T?>

safeActor

inline fun <T> CoroutineScope.safeActor(channelCapacity: Int = Channel.UNLIMITED, noinline onException: ExceptionHandler<Unit> = defaultSafelyExceptionHandler, crossinline block: suspend (T) -> Unit): Channel<T>

safeActorAsync

inline fun <T> CoroutineScope.safeActorAsync(channelCapacity: Int = Channel.UNLIMITED, noinline onException: ExceptionHandler<Unit> = defaultSafelyExceptionHandler, noinline markerFactory: suspend (T) -> Any? = { null }, crossinline block: suspend (T) -> Unit): Channel<T>

safely

suspend fun <T> safely(onException: ExceptionHandler<T> = defaultSafelyExceptionHandler, block: suspend CoroutineScope.() -> T): T

It will run block inside of supervisorScope to avoid problems with catching of exceptions

safelyWithContextExceptionHandler

suspend fun <T> safelyWithContextExceptionHandler(contextExceptionHandler: ExceptionHandler<Unit>, safelyExceptionHandler: ExceptionHandler<T> = defaultSafelyExceptionHandler, block: suspend CoroutineScope.() -> T): T

This method will set new coroutineContext with ContextSafelyExceptionHandler. In case if coroutineContext already contains ContextSafelyExceptionHandler, ContextSafelyExceptionHandler.handler will be used BEFORE contextExceptionHandler in case of exception.

safelyWithoutExceptions

suspend fun <T> safelyWithoutExceptions(onException: ExceptionHandler<T?> = defaultSafelyWithoutExceptionHandlerWithNull, block: suspend CoroutineScope.() -> T): T?

Shortcut for safely with exception handler, that as expected must return null in case of impossible creating of result from exception (instead of throwing it, by default always returns null)

safelyWithResult

suspend fun <T> safelyWithResult(block: suspend CoroutineScope.() -> T): Result<T>

safelyWithResult

suspend fun <T, R> T.safelyWithResult(block: suspend T.() -> R): Result<R>

selectFileOrNull

suspend fun selectFileOrNull(inputSetup: (HTMLInputElement) -> Unit = {}, onFailure: (Throwable) -> Unit = {}): MPPFile?

selectFileOrThrow

suspend fun selectFileOrThrow(inputSetup: (HTMLInputElement) -> Unit = {}): MPPFile

setOnHierarchyChangeListenerRecursively

fun ViewGroup.setOnHierarchyChangeListenerRecursively(listener: ViewGroup.OnHierarchyChangeListener)

Use ViewGroup.setOnHierarchyChangeListener recursively for all available ViewGroups starting with this. This extension DO NOT guarantee that recursive subscription will happen after this method call

inline fun <T> Flow<T>.subscribe(scope: CoroutineScope, noinline block: suspend (T) -> Unit): Job

Shortcut for chain if Flow.onEach and Flow.launchIn

subscribeAsync

fun <T, M> Flow<T>.subscribeAsync(scope: CoroutineScope, markerFactory: suspend (T) -> M, block: suspend (T) -> Unit): Job

subscribeSafely

inline fun <T> Flow<T>.subscribeSafely(scope: CoroutineScope, noinline onException: ExceptionHandler<Unit> = defaultSafelyExceptionHandler, noinline block: suspend (T) -> Unit): Job

Use subscribe, but all blocks will be called inside of safely function. Use onException to set up your reaction for Throwables

subscribeSafelyAsync

fun <T, M> Flow<T>.subscribeSafelyAsync(scope: CoroutineScope, markerFactory: suspend (T) -> M, onException: ExceptionHandler<Unit> = defaultSafelyExceptionHandler, block: suspend (T) -> Unit): Job

subscribeSafelySkippingExceptions

inline fun <T> Flow<T>.subscribeSafelySkippingExceptions(scope: CoroutineScope, noinline block: suspend (T) -> Unit): Job

Use subscribeSafelyWithoutExceptions, but all exceptions inside of safely will be skipped

subscribeSafelySkippingExceptionsAsync

fun <T, M> Flow<T>.subscribeSafelySkippingExceptionsAsync(scope: CoroutineScope, markerFactory: suspend (T) -> M, block: suspend (T) -> Unit): Job

subscribeSafelyWithoutExceptions

inline fun <T> Flow<T>.subscribeSafelyWithoutExceptions(scope: CoroutineScope, noinline onException: ExceptionHandler<T?> = defaultSafelyWithoutExceptionHandlerWithNull, noinline block: suspend (T) -> Unit): Job

Use subscribeSafelyWithoutExceptions, but all exceptions will be passed to defaultSafelyExceptionHandler

subscribeSafelyWithoutExceptionsAsync

fun <T, M> Flow<T>.subscribeSafelyWithoutExceptionsAsync(scope: CoroutineScope, markerFactory: suspend (T) -> M, onException: ExceptionHandler<T?> = defaultSafelyWithoutExceptionHandlerWithNull, block: suspend (T) -> Unit): Job

takeNotNull

fun <T> Flow<T>.takeNotNull(): Flow<T & Any>

toByteArray

suspend fun Blob.toByteArray(): ByteArray

visibilityFlow

fun Element.visibilityFlow(): Flow<Boolean>

waitReadRelease

suspend fun SmartRWLocker.waitReadRelease(permits: Int = 1): Int

Will wait until the SmartSemaphore.permitsStateFlow of this instance will have permits count free permits.

waitRelease

suspend fun SmartSemaphore.waitRelease(permits: Int = 1): Int

Will wait until the SmartSemaphore.permitsStateFlow of this instance will have permits count free permits.

waitUnlock

suspend fun SmartMutex.waitUnlock(): Boolean

Will wait until the SmartMutex.lockStateFlow of this instance will be false.

waitWriteUnlock

suspend fun SmartRWLocker.waitWriteUnlock(): Boolean

Will wait until the SmartMutex.lockStateFlow of this instance will be false.

WeakScope

fun WeakScope(context: CoroutineContext): CoroutineScope

Created CoroutineScope which will launch listening of context job completing and drop itself. Current weak scope will not be attached to context directly. So, this CoroutineScope will not prevent parent one from cancelling if it is launched with supervisorScope or coroutineScope, but still will follow closing status of parent Job

fun WeakScope(scope: CoroutineScope): CoroutineScope

Created CoroutineScope which will launch listening of scope job completing and drop itself. Current weak scope will not be attached to scope directly. So, this CoroutineScope will not prevent parent one from cancelling if it is launched with supervisorScope or coroutineScope, but still will follow closing status of parent Job

withAcquire

inline suspend fun <T> SmartSemaphore.Mutable.withAcquire(permits: Int = 1, action: () -> T): T

Will call SmartSemaphore.Mutable.lock, then execute action and return the result after SmartSemaphore.Mutable.unlock

withLock

inline suspend fun <T> SmartMutex.Mutable.withLock(action: () -> T): T

Will call SmartMutex.Mutable.lock, then execute action and return the result after SmartMutex.Mutable.unlock

withReadAcquire

inline suspend fun <T> SmartRWLocker.withReadAcquire(action: () -> T): T

Will call SmartSemaphore.Mutable.lock, then execute action and return the result after SmartSemaphore.Mutable.unlock

withWriteLock

inline suspend fun <T> SmartRWLocker.withWriteLock(action: () -> T): T

Will call SmartMutex.Mutable.lock, then execute action and return the result after SmartMutex.Mutable.unlock