io

Documentation

Overview

Package io implements IO tools similar to what is available in Scala cats library (and Haskell IO).

Index

• Variables
• func RecoverToErrorVar(name string, err *error)
• func ToChannel[A any](ch chan A) func(A) IO[fun.Unit]
• func ToChannelAndClose[A any](ch chan A) func(A) IO[fun.Unit]
• func UnsafeRunSync[A any](io IO[A]) (res A, err error)
• func WithTimeout[A any](d time.Duration) func(ioa IO[A]) IO[A]
• type Callback
• type Fiber
• type GoResult
• type IO
  • func AndThen[A any, B any](ioa IO[A], iob IO[B]) IO[B]
  • func Async[A any](k func(Callback[A])) IO[A]
  • func ConcurrentlyFirst[A any](ios []IO[A]) IO[A]
  • func Delay[A any](f func() IO[A]) IO[A]
  • func Eval[A any](f func() (A, error)) IO[A]
  • func Fail[A any](err error) IO[A]
  • func FireAndForget[A any](ioa IO[A]) IO[fun.Unit]
  • func FlatMap[A any, B any](ioA IO[A], f func(a A) IO[B]) IO[B]
  • func FlatMapErr[A any, B any](ioA IO[A], f func(a A) (B, error)) IO[B]
  • func Fold[A any, B any](io IO[A], f func(a A) IO[B], recover func(error) IO[B]) IO[B]
  • func FoldErr[A any, B any](io IO[A], f func(a A) (B, error), recover func(error) (B, error)) IO[B]
  • func FoldToGoResult[A any](io IO[A]) IO[GoResult[A]]
  • func ForEach[A any](io IO[A], cb func(a A)) IO[fun.Unit]
  • func FromChannel[A any](ch chan A) IO[A]
  • func FromUnit(f func() error) IO[fun.Unit]
  • func Lift[A any](a A) IO[A]
  • func LiftPair[A any](a A, err error) IO[A]
  • func Map[A any, B any](ioA IO[A], f func(a A) B) IO[B]
  • func MapErr[A any, B any](ioA IO[A], f func(a A) (B, error)) IO[B]
  • func Never[A any]() IO[A]
  • func Notify[A any](d time.Duration, value A, cb Callback[A]) IO[fun.Unit]
  • func Parallel[A any](ios []IO[A]) IO[[]A]
  • func Pure[A any](f func() A) IO[A]
  • func Recover[A any](io IO[A], recover func(err error) IO[A]) IO[A]
  • func Sequence[A any](ioas []IO[A]) (res IO[[]A])
  • func Sleep(d time.Duration) IO[fun.Unit]
  • func SleepA[A any](d time.Duration, value A) IO[A]
  • func Start[A any](io IO[A]) IO[Fiber[A]]
  • func StartInGoRoutineAndWaitForResult[A any](io IO[A]) IO[A]
  • func UnfoldGoResult[A any](iogr IO[GoResult[A]]) IO[A]
  • func Unptr[A any](ptra *A) IO[A]
  • func Wrapf[A any](io IO[A], format string, args ...interface{}) IO[A]
• type IOUnit
  • func SequenceUnit(ious []IOUnit) (res IOUnit)

Variables

var ErrorTimeout = errors.New("timeout")

ErrorTimeout is an error that will be returned in case of timeout.

var IOUnit1 = Lift(fun.Unit1)

IOUnit1 is a IO[Unit] that will always return Unit1.

Functions

func RecoverToErrorVar

func RecoverToErrorVar(name string, err *error)

RecoverToErrorVar recovers and places the recovered error into the given variable

func ToChannel

func ToChannel[A any](ch chan A) func(A) IO[fun.Unit]

ToChannel saves the value to the channel

func ToChannelAndClose

func ToChannelAndClose[A any](ch chan A) func(A) IO[fun.Unit]

ToChannelAndClose sends the value to the channel and then closes the channel.

func UnsafeRunSync

func UnsafeRunSync[A any](io IO[A]) (res A, err error)

UnsafeRunSync runs the given IO[A] synchronously and returns the result.

func WithTimeout

func WithTimeout[A any](d time.Duration) func(ioa IO[A]) IO[A]

WithTimeout waits IO for completion for no longer than the provided duration. If there are no results, the IO will fail with timeout error.

Types

type Callback

type Callback[A any] func(A, error)

Callback[A] is a function that takes A and error. A is only valid if error is nil.

type Fiber

type Fiber[A any] interface {
	// Join waits for results of the fiber.
	// When fiber completes, this IO will complete and return the result.
	// After this fiber is closed, all join IOs fail immediately.
	Join() IO[A]
	// Closes the fiber and stops sending callbacks.
	// After closing, the respective go routine may complete
	// This is not Cancel, it does not send any signals to the fiber.
	// The work will still be done.
	Close() IO[fun.Unit]
}

Fiber[A] is a type safe representation of Go routine. One might Join() and receive the result of the go routine. After Close() subsequent joins will fail.

type GoResult

type GoResult[A any] struct {
	Value A
	Error error
}

GoResult[A] is a data structure that represents the Go-style result of a function that could fail.

type IO

type IO[A any] interface {
	// contains filtered or unexported methods
}

IO[A] represents a calculation that will yield a value of type A once executed. The calculation might as well fail. It is designed to not panic ever.

func AndThen

func AndThen[A any, B any](ioa IO[A], iob IO[B]) IO[B]

AndThen runs the first IO, ignores it's result and then runs the second one.

func Async

func Async[A any](k func(Callback[A])) IO[A]

Async[A] constructs an IO given a function that will eventually call a callback. Internally this function creates a channel and blocks on in until the function calls it.

func ConcurrentlyFirst

func ConcurrentlyFirst[A any](ios []IO[A]) IO[A]

ConcurrentlyFirst - runs all IOs in parallel. returns the very first result. TODO: after obtaining result - cancel the other IOs.

func Delay

func Delay[A any](f func() IO[A]) IO[A]

Delay[A] wraps a function that will then return an IO.

func Eval

func Eval[A any](f func() (A, error)) IO[A]

Eval[A] constructs an IO[A] from a simple function that might fail. If there is panic in the function, it's recovered from and represented as an error.

func Fail

func Fail[A any](err error) IO[A]

Fail[A] constructs an IO[A] that fails with the given error.

func FireAndForget

func FireAndForget[A any](ioa IO[A]) IO[fun.Unit]

FireAndForget runs the given IO in a go routine and ignores the result It uses Fiber underneath.

func FlatMap

func FlatMap[A any, B any](ioA IO[A], f func(a A) IO[B]) IO[B]

FlatMap converts the result of IO[A] using a function that itself returns an IO[B]. It'll fail if any of IO[A] or IO[B] fail.

func FlatMapErr

func FlatMapErr[A any, B any](ioA IO[A], f func(a A) (B, error)) IO[B]

FlatMapErr converts IO[A] result using a function that might fail. It seems to be identical to MapErr.

func Fold

func Fold[A any, B any](io IO[A], f func(a A) IO[B], recover func(error) IO[B]) IO[B]

Fold performs different calculations based on whether IO[A] failed or succeeded.

func FoldErr

func FoldErr[A any, B any](io IO[A], f func(a A) (B, error), recover func(error) (B, error)) IO[B]

FoldErr folds IO using simple Go-style functions that might fail.

func FoldToGoResult

func FoldToGoResult[A any](io IO[A]) IO[GoResult[A]]

FoldToGoResult converts either value or error to go result typically it should never fail.

func ForEach

func ForEach[A any](io IO[A], cb func(a A)) IO[fun.Unit]

ForEach calls the provided callback after IO is completed.

func FromChannel

func FromChannel[A any](ch chan A) IO[A]

FromChannel reads a single value from the channel

func FromUnit

func FromUnit(f func() error) IO[fun.Unit]

FromUnit consturcts IO[fun.Unit] from a simple function that might fail.

func Lift

func Lift[A any](a A) IO[A]

Lift[A] constructs an IO[A] from a constant value.

func LiftPair

func LiftPair[A any](a A, err error) IO[A]

LiftPair[A] constructs an IO from constant values.

func Map

func Map[A any, B any](ioA IO[A], f func(a A) B) IO[B]

Map converts the IO[A] result using the provided function that cannot fail.

func MapErr

func MapErr[A any, B any](ioA IO[A], f func(a A) (B, error)) IO[B]

MapErr maps the result of IO[A] using a function that might fail.

func Never

func Never[A any]() IO[A]

Never is a simple IO that never returns

func Notify

func Notify[A any](d time.Duration, value A, cb Callback[A]) IO[fun.Unit]

Notify starts a separate thread that will call the given callback after the specified time.

func Parallel

func Parallel[A any](ios []IO[A]) IO[[]A]

Parallel starts the given IOs in Go routines and waits for all results

func Pure

func Pure[A any](f func() A) IO[A]

Pure[A] constructs an IO[A] from a function that cannot fail.

func Recover

func Recover[A any](io IO[A], recover func(err error) IO[A]) IO[A]

Recover handles a potential error from IO. It does not fail itself.

func Sequence

func Sequence[A any](ioas []IO[A]) (res IO[[]A])

Sequence takes a slice of IOs and returns an IO that will contain a slice of results. It'll fail if any of the internal computations fail.

func Sleep

func Sleep(d time.Duration) IO[fun.Unit]

Sleep makes the IO sleep the specified time.

func SleepA

func SleepA[A any](d time.Duration, value A) IO[A]

SleepA sleeps and then returns the constant value.

func Start

func Start[A any](io IO[A]) IO[Fiber[A]]

Start will start the IO in a separate go-routine. It'll establish a channel with callbacks, so that any number of listeners could join the returned fiber. When completed it'll start sending the results to the callbacks. The same value will be delivered to all listeners.

func StartInGoRoutineAndWaitForResult

func StartInGoRoutineAndWaitForResult[A any](io IO[A]) IO[A]

StartInGoRoutineAndWaitForResult - not very useful function. While it executes the IO in the go routine, the current thread is blocked.

func UnfoldGoResult

func UnfoldGoResult[A any](iogr IO[GoResult[A]]) IO[A]

UnfoldGoResult represents GoResult back to ordinary IO.

func Unptr

func Unptr[A any](ptra *A) IO[A]

Unptr retrieves the value at pointer. Fails if nil

func Wrapf

func Wrapf[A any](io IO[A], format string, args ...interface{}) IO[A]

Wrapf wraps an error with additional context information

type IOUnit

type IOUnit = IO[fun.Unit]

IOUnit is IO[Unit]

func SequenceUnit

func SequenceUnit(ious []IOUnit) (res IOUnit)

SequenceUnit takes a slice of IO units and returns IO that executes all of them. It'll fail if any of the internal computations fail.