Package com.jnape.palatable.lambda.io
Class IO<A>
java.lang.Object
com.jnape.palatable.lambda.io.IO<A>
- Type Parameters:
A
- the result type
- All Implemented Interfaces:
Applicative<A,
,IO<?>> Functor<A,
,IO<?>> Monad<A,
,IO<?>> MonadError<Throwable,
,A, IO<?>> MonadRec<A,
IO<?>>
- Direct Known Subclasses:
IO.Compose
-
Nested Class Summary
Nested Classes -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal <B> IO
<B> discardL
(Applicative<B, IO<?>> appB) Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
.discardR
(Applicative<B, IO<?>> appB) Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
.exceptionally
(Fn1<? super Throwable, ? extends A> recoveryFn) Deprecated.static <A> IO
<A> externallyManaged
(Fn0<CompletableFuture<A>> supplier) Static factory method for creating anIO
from an externally managed source ofcompletable futures
.final <B> IO
<B> Chain dependent computations that may continue or short-circuit based on previous results.final <B> IO
<B> Covariantly transmute this functor's parameter using the given mapping function.static <A> IO
<A> Fuse all fork opportunities of a givenIO
such that, unless it ispinned
(or is originallyexternally managed
), no parallelism will be used when running it, regardless of what semantics are used when it is executed.static <A> IO
<A> interruptible
(IO<A> io) static <A> IO
<A> io
(A a) Static factory method for creating anIO
that just returnsa
when performed.static <A> IO
<A> Static factory method for coercing a lambda to anIO
.io
(SideEffect sideEffect) Given alazy
instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.static <A> IO
<A> static <A> IO
<A> monitorSync
(Object lock, IO<A> io) Synchronize the givenIO
using the provided lock object.static <A> IO
<A> final <B> IO
<B> pure
(B b) Lift the valueb
into this applicative functor.pureIO()
safe()
throwError
(Throwable throwable) Throw an error value of typeE
into themonad
.static <A> IO
<A> <B> IO
<B> trampolineM
(Fn1<? super A, ? extends MonadRec<RecursiveResult<A, B>, IO<?>>> fn) Given some operation yielding aRecursiveResult
inside thisMonadRec
, internally trampoline the operation until it yields atermination
instruction.final CompletableFuture
<A> Returns aCompletableFuture
representing the result of this eventual effect.abstract CompletableFuture
<A> unsafePerformAsyncIO
(Executor executor) Returns aCompletableFuture
representing the result of this eventual effect.abstract A
Run the effect represented by thisIO
instance, blocking the current thread until the effect terminates.final <B> IO
<B> zip
(Applicative<Fn1<? super A, ? extends B>, IO<?>> appFn) Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
-
Constructor Details
-
IO
private IO()
-
-
Method Details
-
unsafePerformIO
Run the effect represented by thisIO
instance, blocking the current thread until the effect terminates.- Returns:
- the result of the effect
-
unsafePerformAsyncIO
Returns aCompletableFuture
representing the result of this eventual effect. By default, this will immediately run the effect in terms of the implicitExecutor
available toCompletableFuture
(usually theForkJoinPool
). Note that specificIO
constructions may allow this method to delegate to externally-managedCompletableFuture
instead of synthesizing their own.- Returns:
- the
CompletableFuture
representing thisIO
's eventual result - See Also:
-
unsafePerformAsyncIO
Returns aCompletableFuture
representing the result of this eventual effect. By default, this will immediately run the effect in terms of the providedExecutor
. Note that specificIO
constructions may allow this method to delegate to externally-managedCompletableFuture
instead of synthesizing their own.- Parameters:
executor
- theExecutor
to run theCompletableFuture
from- Returns:
- the
CompletableFuture
representing thisIO
's eventual result - See Also:
-
exceptionally
Deprecated.in favor of canonicalcatchError(Fn1)
Given a function from anyThrowable
to the result typeA
, if thisIO
successfully yields a result, return it; otherwise, map theThrowable
to the result type and return that.- Parameters:
recoveryFn
- the recovery function- Returns:
- the guarded
IO
-
ensuring
-
safe
Return a safeIO
that will never throw by lifting the result of thisIO
intoEither
, catching anyThrowable
and wrapping it in aleft
.- Returns:
- the safe
IO
-
pure
Lift the valueb
into this applicative functor.- Specified by:
pure
in interfaceApplicative<A,
IO<?>> - Specified by:
pure
in interfaceMonad<A,
IO<?>> - Specified by:
pure
in interfaceMonadError<Throwable,
A, IO<?>> - Specified by:
pure
in interfaceMonadRec<A,
IO<?>> - Type Parameters:
B
- the type of the returned applicative's parameter- Parameters:
b
- the value- Returns:
- an instance of this applicative over b
-
fmap
Covariantly transmute this functor's parameter using the given mapping function. Generally this method is specialized to return an instance of the class implementing Functor.- Specified by:
fmap
in interfaceApplicative<A,
IO<?>> - Specified by:
fmap
in interfaceFunctor<A,
IO<?>> - Specified by:
fmap
in interfaceMonad<A,
IO<?>> - Specified by:
fmap
in interfaceMonadError<Throwable,
A, IO<?>> - Specified by:
fmap
in interfaceMonadRec<A,
IO<?>> - Type Parameters:
B
- the new parameter type- Parameters:
fn
- the mapping function- Returns:
- a functor over B (the new parameter type)
-
zip
Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.- Specified by:
zip
in interfaceApplicative<A,
IO<?>> - Specified by:
zip
in interfaceMonad<A,
IO<?>> - Specified by:
zip
in interfaceMonadError<Throwable,
A, IO<?>> - Specified by:
zip
in interfaceMonadRec<A,
IO<?>> - Type Parameters:
B
- the resulting applicative parameter type- Parameters:
appFn
- the other applicative instance- Returns:
- the mapped applicative
-
lazyZip
public final <B> Lazy<IO<B>> lazyZip(Lazy<? extends Applicative<Fn1<? super A, ? extends B>, IO<?>>> lazyAppFn) Given alazy
instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports. This is useful for applicatives that support lazy evaluation and early termination.- Specified by:
lazyZip
in interfaceApplicative<A,
IO<?>> - Specified by:
lazyZip
in interfaceMonad<A,
IO<?>> - Specified by:
lazyZip
in interfaceMonadError<Throwable,
A, IO<?>> - Specified by:
lazyZip
in interfaceMonadRec<A,
IO<?>> - Type Parameters:
B
- the resulting applicative parameter type- Parameters:
lazyAppFn
- the lazy other applicative instance- Returns:
- the mapped applicative
- See Also:
-
discardL
Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
. This is generally useful for sequentially performing side-effects.- Specified by:
discardL
in interfaceApplicative<A,
IO<?>> - Specified by:
discardL
in interfaceMonad<A,
IO<?>> - Specified by:
discardL
in interfaceMonadError<Throwable,
A, IO<?>> - Specified by:
discardL
in interfaceMonadRec<A,
IO<?>> - Type Parameters:
B
- the type of the returned Applicative's parameter- Parameters:
appB
- the other Applicative- Returns:
- appB
-
discardR
Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
. This is generally useful for sequentially performing side-effects.- Specified by:
discardR
in interfaceApplicative<A,
IO<?>> - Specified by:
discardR
in interfaceMonad<A,
IO<?>> - Specified by:
discardR
in interfaceMonadError<Throwable,
A, IO<?>> - Specified by:
discardR
in interfaceMonadRec<A,
IO<?>> - Type Parameters:
B
- the type of appB's parameter- Parameters:
appB
- the other Applicative- Returns:
- this Applicative
-
flatMap
Chain dependent computations that may continue or short-circuit based on previous results.- Specified by:
flatMap
in interfaceMonad<A,
IO<?>> - Specified by:
flatMap
in interfaceMonadError<Throwable,
A, IO<?>> - Specified by:
flatMap
in interfaceMonadRec<A,
IO<?>> - Type Parameters:
B
- the resulting monad parameter type- Parameters:
f
- the dependent computation over A- Returns:
- the new monad instance
-
trampolineM
Given some operation yielding aRecursiveResult
inside thisMonadRec
, internally trampoline the operation until it yields atermination
instruction.Stack-safety depends on implementations guaranteeing that the growth of the call stack is a constant factor independent of the number of invocations of the operation. For various examples of how this can be achieved in stereotypical circumstances, see the referenced types.
- Specified by:
trampolineM
in interfaceMonadRec<A,
IO<?>> - Type Parameters:
B
- the ultimate resulting carrier type- Parameters:
fn
- the function to internally trampoline- Returns:
- the trampolined
MonadRec
- See Also:
-
throwError
Throw an error value of typeE
into themonad
.- Specified by:
throwError
in interfaceMonadError<Throwable,
A, IO<?>> - Parameters:
throwable
- the error type- Returns:
- the
monad
-
catchError
- Specified by:
catchError
in interfaceMonadError<Throwable,
A, IO<?>> - Parameters:
recoveryFn
- the catch function- Returns:
- the recovered
Monad
-
throwing
-
interruptible
Wrap the givenIO
in anIO
that first checks if thethread
theIO
runs on isinterrupted
. If it is, anInterruptedException
is thrown; otherwise the givenIO
is executed as usual. Note that forIO
s supporting parallelism, the thread that is checked for interruption may not necessarily be the same thread that theIO
ultimately runs on.- Type Parameters:
A
- theIO
result type- Parameters:
io
- theIO
to wrap- Returns:
- an
IO
that first checks forthread interrupts
-
monitorSync
Synchronize the givenIO
using the provided lock object. Note that to ensure that the entirety of theIO
's computation actually runs inside the synchronized region, theIO
is executedsynchronously
inside the synchronized block regardless of the caller's chosen execution strategy. -
fuse
Fuse all fork opportunities of a givenIO
such that, unless it ispinned
(or is originallyexternally managed
), no parallelism will be used when running it, regardless of what semantics are used when it is executed. -
pin
Pin anIO
to anExecutor
such that regardless of what future decisions are made, when it runs, it will run using whatever parallelism is supported by theExecutor
's threading model. Note that if thisIO
has already been pinned (or is originallyexternally managed
), pinning to an additionalExecutor
has no meaningful effect. -
memoize
Given anIO
, return anIO
that wraps it, caches its first successful result, and guarantees that no subsequent interactions will happen with it afterwards, returning the cached result thereafter. Note that if the underlyingIO
throws, the failure will not be cached, so subsequent interactions with the memoizedIO
will again call through to the delegate until it completes normally. -
io
Static factory method for creating anIO
that just returnsa
when performed.- Type Parameters:
A
- the result type- Parameters:
a
- the result- Returns:
- the
IO
-
io
Static factory method for coercing a lambda to anIO
.- Type Parameters:
A
- the result type- Parameters:
fn0
- the lambda to coerce- Returns:
- the
IO
-
io
- Parameters:
sideEffect
- theSideEffect
- Returns:
- the
IO
-
externallyManaged
Static factory method for creating anIO
from an externally managed source ofcompletable futures
.Note that constructing an
IO
this way results in no intermediate futures being constructed by eitherunsafePerformAsyncIO()
orunsafePerformAsyncIO(Executor)
, andunsafePerformIO()
is synonymous with invokingCompletableFuture.get()
on the externally managed future.- Type Parameters:
A
- the result type- Parameters:
supplier
- the source of externally managedcompletable futures
- Returns:
- the
IO
-
pureIO
- Returns:
- the
Pure
instance
-
catchError(Fn1)