A pattern for safe usage of resources. Supports monadic operations so usage can be composed.
It's similar to:
- the using statement in C#
- the try-with-resources statement introduced in Java JDK 7
But also acts as a Factory for instantiating initialized instances of a type.
Lifecycle was born of frustration, aiming to help your codebase tidy up all used resources. It's a nice try / finally wrapper!
A resource is anything that requires:
- Some intialization operations
- And/or some tear-down operations
to be performed between use. For example, a file:
- Must be opened before any read/write operations are performed
- Any pending writes should be flushed, and the file handle returned to the OS after use
Stable:
"com.itv" %% "lifecycle" % "0.3"
Meet bob, fred, and barry.
They each have a secret, but they'll only reveal it to you if you say hello first. After you're done using them, you should say goodbye - it'd be pretty rude not to.
case class Person(name: String, private val secret: String) {
private var readyToTellSecret = false
def hello(): Unit = {
readyToTellSecret = true
println("Said hello to " + name)
}
def revealSecret(): String = {
require(readyToTellSecret, s"it's rude to ask $name a secret before you've said hello")
secret
}
def goodbye(): Unit = {
readyToTellSecret = false
println("Said goodbye to " + name)
}
}scala> val bob = Person("Bob", secret = "I hate Barry")
bob: Person = Person(Bob,I hate Barry)
scala> val fred = Person("Fred", secret = "I hate Barry")
fred: Person = Person(Fred,I hate Barry)
scala> val barry = Person("Barry", secret = "I'm lonely")
barry: Person = Person(Barry,I'm lonely)bob, fred and barry aren't going to win any prizes for lack of side-effects, but you've got to expect the unexpected when dealing with people.
You're gonna have a bad time if you ask bob his secret before saying hello:
scala> bob.revealSecret()
java.lang.IllegalArgumentException: requirement failed: it's rude to ask Bob a secret before you've said hello
at scala.Predef$.require(Predef.scala:224)
at Person.revealSecret(<console>:21)
... 382 elidedWe always need to guarantee we interact with a Person in this manner:
scala> bob.hello()
Said hello to Bob
scala> bob.revealSecret()
res2: String = I hate Barry
scala> bob.goodbye()
Said goodbye to BobHere's a Lifecycle that performs all the pleaseantries before/after using a Person.
scala> import com.itv.lifecycle._
import com.itv.lifecycle._
scala> def personInteraction(person: Person): Lifecycle[Person] =
| new VanillaLifecycle[Person] {
| override def start(): Person = {
| person.hello()
| person
| }
|
| override def shutdown(instance: Person): Unit =
| person.goodbye()
| }
personInteraction: (person: Person)com.itv.lifecycle.Lifecycle[Person]start produces an initialized instance of a Person. shutdown should always be performed after using a Person: even if the interaction caused an exception to be thrown.
Note: in this example we perform the start operations on a pre-instantiated Person: but it's perfectly valid to instantiate the resource within the start method of a Lifecycle.
We want to grab the secret of an individual Person, and print it to stdout.
scala> def announceSecret(person: Person) = {
| val secret: String = Lifecycle.using(personInteraction(person)) { greetedPerson =>
| println("Asking secret")
| greetedPerson.revealSecret()
| }
|
| println(s"${person.name}'s secret is '$secret'")
| }
announceSecret: (person: Person)Unit
scala> announceSecret(bob)
Said hello to Bob
Asking secret
Said goodbye to Bob
Bob's secret is 'I hate Barry'
scala> announceSecret(fred)
Said hello to Fred
Asking secret
Said goodbye to Fred
Fred's secret is 'I hate Barry'
scala> announceSecret(barry)
Said hello to Barry
Asking secret
Said goodbye to Barry
Barry's secret is 'I'm lonely'We have used Lifecycle.using to interact safely with a given Lifecycle[Person]:
def using[T, S](lifecycle: Lifecycle[T])(block: T => S): SThe using method:
- Gets an instance of
Tby using thestartmethod of the givenLifecycle - Uses a block of code you provide to produce an
S - Guarantees the
shutdownmethod of the givenLifecycleis called with theTinstance: even if the block of code you provided threw an exception - Returns the
Syour block of code produced
The code block we called Lifecycle.using with is pretty tame: it's unlikely to throw an exception.
What if there was a strong chance our code block will fail in an unexpected manner? We should still be courteous and ensure we say goodbye to the Person we're interacting with.
Let's write a method called judgeThenAnnounce. This method will also interact with an individual Person.
It will judge their secret: and throw an exception if they're being unkind. Otherwise it will return the secret without exception.
scala> def judgeThenAnnounce(person: Person) = {
| val secret: String = Lifecycle.using(personInteraction(person)) { greetedPerson =>
| println("Asking secret")
| val revealedSecret: String = greetedPerson.revealSecret()
|
| if (revealedSecret contains "hate")
| throw new IllegalStateException(s"I'm not going to repeat what ${greetedPerson.name} just said to me.")
| else
| revealedSecret
| }
|
| println(s"${person.name}'s secret is '$secret'")
| }
judgeThenAnnounce: (person: Person)Unitscala> judgeThenAnnounce(bob)
Said hello to Bob
Asking secret
Said goodbye to Bob
java.lang.IllegalStateException: I'm not going to repeat what Bob just said to me.
at $anonfun$1.apply(<console>:24)
at $anonfun$1.apply(<console>:19)
at com.itv.lifecycle.Lifecycle$.using(Lifecycle.scala:51)
at .judgeThenAnnounce(<console>:19)
... 746 elidedscala> judgeThenAnnounce(fred)
Said hello to Fred
Asking secret
Said goodbye to Fred
java.lang.IllegalStateException: I'm not going to repeat what Fred just said to me.
at $anonfun$1.apply(<console>:24)
at $anonfun$1.apply(<console>:19)
at com.itv.lifecycle.Lifecycle$.using(Lifecycle.scala:51)
at .judgeThenAnnounce(<console>:19)
... 758 elidedscala> judgeThenAnnounce(barry)
Said hello to Barry
Asking secret
Said goodbye to Barry
Barry's secret is 'I'm lonely'Looks good eh? Even though our code block blew up a couple of times due to the extreme views of bob and fred, we were courteous to each Person: always saying hello and goodbye.
Let's extend this example further, and interact with multiple greeted People at the same time.
We will say a Person is friends with another Person if they both share the same secret.
scala> def areFriends(personA: Person, personB: Person): Boolean = {
| val interrogation = for {
| a <- personInteraction(personA)
| b <- personInteraction(personB)
| }
| yield (a.revealSecret(), b.revealSecret())
|
| Lifecycle.using(interrogation) {
| case (secretA, secretB) =>
| secretA == secretB
| }
| }
areFriends: (personA: Person, personB: Person)Boolean
scala> areFriends(bob, fred)
Said hello to Bob
Said hello to Fred
Said goodbye to Fred
Said goodbye to Bob
res10: Boolean = true
scala> areFriends(bob, barry)
Said hello to Bob
Said hello to Barry
Said goodbye to Barry
Said goodbye to Bob
res11: Boolean = false
scala> areFriends(fred, barry)
Said hello to Fred
Said hello to Barry
Said goodbye to Barry
Said goodbye to Fred
res12: Boolean = false
scala> areFriends(barry, barry)
Said hello to Barry
Said hello to Barry
Said goodbye to Barry
Said goodbye to Barry
res13: Boolean = trueWe can map and flatMap a Lifeycle just like any other container. We get the same resource safety guarantees:
scala> personInteraction(bob).map(_.revealSecret().toUpperCase).foreach(println)
Said hello to Bob
I HATE BARRY
Said goodbye to BobNote: in this example we're only interacting with Person instances, this is not a limitation, you can combine Lifecycle's of different intance types in the exact same manner.
Our typical usage is for our entire program to be defined within a single Lifeycle.
scala> trait HttpServer {
| def stop(): Unit = println("stopped")
| }
defined trait HttpServer
scala> val httpServerLifecycle: Lifecycle[HttpServer] =
| new VanillaLifecycle[HttpServer] {
| override def start: HttpServer = {
| val server: HttpServer = new HttpServer {}
| /**
| Construct some HTTP server, bind it to a port and establish request routes
| **/
| println("started")
| server
| }
|
| override def shutdown(instance: HttpServer) =
| instance.stop()
| }
httpServerLifecycle: com.itv.lifecycle.Lifecycle[HttpServer] = $anon$1@6cd81f3fLifecycle has a method that will help with this: runUntilJvmShutdown.
httpServerLifecycle.runUntilJvmShutdownThis will start an instance using the Lifecycle, and register the shutdown method to be run on the instance when the JVM exits.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent