Skip to main content
Version: 2.x

Introduction

ZIO contains a few data types that can help you solve complex problems in asynchronous and concurrent programming. ZIO data types categorize into these sections:

  1. Core Data Types
  2. Control Flow
  3. Scheduling
  4. Contextual Data Types
  5. State Management
  6. Concurrency
  7. Resource Management
  8. Streaming
  9. Logging
  10. Metrics
  11. Testing
  12. Miscellaneous

Core Data Types​

  • ZIO — ZIO is a value that models an effectful program, which might fail or succeed.
    • UIO — UIO[A] is a type alias for ZIO[Any, Nothing, A].
    • URIO — URIO[R, A] is a type alias for ZIO[R, Nothing, A].
    • Task — Task[A] is a type alias for ZIO[Any, Throwable, A].
    • RIO — RIO[R, A] is a type alias for ZIO[R, Throwable, A].
    • IO — IO[E, A] is a type alias for ZIO[Any, E, A].
  • ZIOApp — ZIOApp and the ZIOAppDefault are entry points for ZIO applications.
  • Runtime — Runtime[R] is capable of executing tasks within an environment R.
  • Exit — Exit[E, A] describes the result of executing an IO value.
  • Cause — Cause[E] is a description of a full story of a fiber failure.

Control Flow​

  • Control Flow — ZIO's built-in conditional and looping combinators: when, unless, cond, ifZIO, loop, iterate, foreach, and foreachPar.

Scheduling​

  • Schedule — Schedule[-Env, -In, +Out] is a composable, time-aware state machine for repeating and retrying ZIO effects with full control over timing, delays, and recurrence logic.

Contextual Data Types​

  • ZEnvironment — ZEnvironment[R] is a built-in type-level map for the ZIO data type which is responsible for maintaining the environment of a ZIO effect.
  • ZLayer — ZLayer[-RIn, +E, +ROut] is a recipe to build an environment of type ROut, starting from a value RIn, and possibly producing an error E during creation.
    • RLayer — RLayer[-RIn, +ROut] is a type alias for ZLayer[RIn, Throwable, ROut], which represents a layer that requires RIn as its input, it may fail with Throwable value, or returns ROut as its output.
    • ULayer — ULayer[+ROut] is a type alias for ZLayer[Any, Nothing, ROut], which represents a layer that doesn't require any services as its input, it can't fail, and returns ROut as its output.
    • Layer — Layer[+E, +ROut] is a type alias for ZLayer[Any, E, ROut], which represents a layer that doesn't require any services, it may fail with an error type of E, and returns ROut as its output.
    • URLayer — URLayer[-RIn, +ROut] is a type alias for ZLayer[RIn, Nothing, ROut], which represents a layer that requires RIn as its input, it can't fail, and returns ROut as its output.
    • TaskLayer — TaskLayer[+ROut] is a type alias for ZLayer[Any, Throwable, ROut], which represents a layer that doesn't require any services as its input, it may fail with Throwable value, and returns ROut as its output.

State Management​

  • ZState— It models a state that can be read from and written to during the execution of an effect.
  • Ref— Ref[A] models a mutable reference to a value of type A.
  • FiberRef— FiberRef[A] models a mutable reference to a value of type A. As opposed to Ref[A], a value is bound to an executing Fiber only. You can think of it as Java's ThreadLocal on steroids.
  • ThreadLocalBridge— A service that synchronizes FiberRef values with Java ThreadLocal variables for seamless interoperability with legacy code and libraries that rely on thread-local storage.

Concurrency​

Fiber Primitives​

  • Fiber — A fiber value models an IO value that has started running, and is the moral equivalent of a green thread.
  • Fiber.Status — Fiber.Status describe the current status of a Fiber.
  • FiberId — FiberId describe the unique identity of a Fiber.

Concurrency Primitives​

  • Hub — A Hub is an asynchronous message hub that allows publishers to efficiently broadcast values to many subscribers.
  • Promise — A Promise is a model of a variable that may be set a single time, and awaited on by many fibers.
  • Queue — A Queue is an asynchronous queue that never blocks, which is safe for multiple concurrent producers and consumers.
  • Semaphore — A Semaphore is an asynchronous (non-blocking) semaphore that plays well with ZIO's interruption.
  • Ref — Ref[A] models a mutable reference to a value of type A. The two basic operations are set, which fills the Ref with a new value, and get, which retrieves its current content. All operations on a Ref are atomic and thread-safe, providing a reliable foundation for synchronizing concurrent programs.
  • Ref.Synchronized — Ref.Synchronized[A] models a mutable reference to a value of type A in which we can store immutable data, and update it atomically and effectfully.

Synchronization Aids​

  • ReentrantLock— The ReentrantLock is a synchronization tool that is useful for synchronizing blocks of code.
  • CountdownLatch — A synchronization aid that allows one or more fibers to wait until a set of operations being performed in other fibers completes.
  • CyclicBarrier — A synchronization aid that allows a set of fibers to all wait for each other to reach a common barrier point.
  • ConcurrentMap — A Map wrapper over java.util.concurrent.ConcurrentHashMap
  • ConcurrentSet — A Set implementation over java.util.concurrent.ConcurrentHashMap

STM​

  • STM — An STM represents an effect that can be performed transactionally resulting in a failure or success.
  • TArray — A TArray is an array of mutable references that can participate in transactions.
  • TSet — A TSet is a mutable set that can participate in transactions.
  • TMap — A TMap is a mutable map that can participate in transactions.
  • TRef — A TRef is a mutable reference to an immutable value that can participate in transactions.
  • TPriorityQueue — A TPriorityQueue is a mutable priority queue that can participate in transactions.
  • TPromise — A TPromise is a mutable reference that can be set exactly once and can participate in transactions.
  • TQueue — A TQueue is a mutable queue that can participate in transactions.
  • TReentrantLock — A TReentrantLock is a reentrant read / write lock that can be composed.
  • TSemaphore — A TSemaphore is a semaphore that can participate in transactions.

Resource Management​

  • Cached — A container for a possibly resourceful value that is loaded into memory and can be refreshed either manually or automatically according to a schedule.
  • Scope — A scope in which resources can safely be used.
  • ScopedRef — A resourceful mutable reference that automatically manages acquisition and release of scoped resources.
  • ZPool — An asynchronous and concurrent generalized pool of reusable resources.

Streaming​

  • ZStream — ZStream is a lazy, concurrent, asynchronous source of values.
    • Stream — Stream[E, A] is a type alias for ZStream[Any, E, A], which represents a ZIO stream that does not require any services, and may fail with an E, or produce elements with an A.
  • ZSink — ZSink is a consumer of values from a ZStream, which may produce a value when it has consumed enough.
    • Sink — Sink[InErr, A, OutErr, L, B] is a type alias for ZSink[Any, InErr, A, OutErr, L, B].
  • ZPipeline — ZPipeline is a polymorphic stream transformer.
  • SubscriptionRef — SubscriptionRef[A] contains a current value of type A and a stream that can be consumed to observe all changes to that value.

Logging​

  • ZLogger — ZLogger[-Message, +Output] is ZIO's pure functional logging interface. It can be composed, filtered, and fan-out across multiple destinations without global mutable state.

Metrics​

IO supports 5 types of Metrics:

  • Counter — The Counter is used for any value that increases over time like request counts.
  • Gauge — The gauge is a single numerical value that can arbitrary goes up or down over time like memory usage.
  • Histogram — The Histogram is used to track the distribution of a set of observed values across a set of buckets like request latencies.
  • Summary — The Summary represents a sliding window of a time series along with metrics for certain percentiles of the time series, referred to as quantiles like request latencies.
  • Frequency — The Frequency is a metric that counts the number of occurrences of distinct string values.

Testing​

  • Spec— A Spec[R, E] is the backbone of ZIO Test. All specs require an environment of type R and may potentially fail with an error of type E.
  • Assertion— An Assertion[A] is a test assertion that can be used to assert the predicate of type A => Boolean.
  • TestAspect— A TestAspect is an aspect that can be weaved into specs. We can think of an aspect as a polymorphic function, capable of transforming one test into another.
  • Gen— A Gen[R, A] represents a generator of values of type A, which requires an environment R.
  • Test Service— ZIO Test has the following out-of-the-box test services:
    • TestConsole— It allows testing of applications that interact with the console.
    • TestClock— We can deterministically and efficiently test effects involving the passage of time without actually having to wait for the full amount of time to pass.
    • TestRandom— This service allows us having fully deterministic testing of code that deals with Randomness.
    • TestSystem— It supports deterministic testing of effects involving system properties.
    • Live— It provides access to the live environment from within the test environment for effects.
    • TestConfig— It provides access to default configuration settings used by ZIO Test.
    • Sized— It enables Sized Generators to access the size from the ZIO Test environment.

Miscellaneous​

  • Chunk— Chunk is a fast, pure alternative to Arrays.
  • Supervisor— Supervisor[A] is allowed to supervise the launching and termination of fibers, producing some visible value of type A from the supervision.

To learn more about these data types, please explore the pages above, or check out the Scaladoc documentation.