Peloton aims to be a lightweight and playful actor library for Cats Effect. It provides support for

• Actor systems: control the lifespan of actors and ensure safe resource management.
• Stateful actors: actors that hold and modify a state of a specific type in memory.
• Event sourced actors: actors that convert messages to events that are persisted in an event store and replayed adter the actor restarts.
• Durable state actors: actors that hold a state of a specific type in memory and can store the state in a durable state store. This state is then restored automatically after the actor restarts.
• Message stashes: each actor is able to postpone the processing of incoming messages by pushing them to a stash and can pull back the messages from the stash later
• Changing behavior: the actor's message handler, i.e., the current behavior, possibly returns a new behavior - depending on the actor's state and/or the message.
• Remote actors: an actor system can provide an HTTP interface to other actor system on different hosts and make its local actors available to these actor systems.
• Scheduled effects: effects can be scheduled using a Quartz-compatible CRON expression and triggered and evaluated in the background.

Peloton actors are designed to work together with your Cats Effect application. All actor operations and interactions are effectful in the IO effect type.

The Peloton library is split into separate packages. This allows you to just include what you really need.

For the core Peloton functionality (which is, in fact, all but database-specific persistence drivers), add the following dependency to your build.sbt file:

// See the latest release version on the badge above
val PelotonVersion = "<version>"

// Peloton base functionality
libraryDependencies += "de.killaitis" %% "peloton-core" % PelotonVersion

In order to use persistent actors (durable state or event sourced), you have to add a Peloton persistence module to your build.sbt file that supports your database:

// Optional drivers for Peloton persistent actors
libraryDependencies += "de.killaitis" %% "peloton-persistence-postgresql" % PelotonVersion
libraryDependencies += "de.killaitis" %% "peloton-persistence-mysql" % PelotonVersion     // experimental
libraryDependencies += "de.killaitis" %% "peloton-persistence-cassandra" % PelotonVersion // experimental

There is also a module that allows for scheduling Cats Effect IO actions in the background using the Quartz CRON scheduler. To use it, add the following dependency to your build.sbt file:

// CRON-based background scheduling of Cats Effect actions.
libraryDependencies += "de.killaitis" %% "peloton-scheduling-cron" % PelotonVersion

Peloton is only available for Scala 3. Support for older releases of Scala is currently not planned.

To give an overview of the architecture and terminology of Peloton, refer to the introduction to Peloton.

For a quick start, example code can be found in the examples folder.

You can also find additional information about Peloton actors in the Peloton tests

An Peloton configuration description and reference can be found here.