John Murray

Bastard Go - Try

Mon, 27 Nov 2017 00:00:00 +0000

Premise

Go is great. Scala is great. Scala has Trys. Go doesn’t.

Motivation

I’m a horrible person. ¯\_(ツ)_/¯

Horribleness

In Go it’s typical to return errors as soon as they happen and handle them locally, or wrap them with some additional context and pass them back up the stack. In Scala however it’s idiomatic to wrap an error into a Try which represents either a successfully computed value or an error. The advantage of a Try over a 2-tuple (or multiple return-values) is that the Try can be composed so that you can chain functions together and worry if they failed later, allowing the error to cascade. An example in Scala might look like:

def configLoad()                   : Try[String]         = ???
def getDbConnection(s: String)     : Try[sql.Connection] = ???
def queryForData(c: sql.Connection): Try[sql.Result]     = ???
def transformResults(r: sql.Result): Try[app.MyModel]    = ???

val model: Try[app.MyModel] =
  for {
    s <- configLoad()
    c <- getDbConnection(s)
    r <- queryForData(c)
    m <- transformResults(r)
  } yield (m)

Look how readable that is! Wow….

Above are several functions, meant to be called in order. Each function returns a possible error and the next function takes the success value of the previous function. The code starting with for { is some syntactic sugar (mmmmmm sugar) that allows us to call map and flatMap which are essentially ways of calling the next function assuming the previous one succeeded. If there was an error, then the value of model will be a failed Try (Failure in Scala) with the error.

This allows the programmer to write code that describes the “happy path”, dealing with errors at the last possible moment (just like real life). Some would argue this style is more readable (if at least not more relatable). ¯\_(ツ)_/¯

To be fair, this programming style has it’s own pattern named after trains and if that isn’t enough to convince you, then I think there are larger issues at play. Go read this two-part post, it’s super good so you should read it without me prompting you anyways: part-1, part-2.

I don’t want this to turn into an in-depth explanation of Try in Scala, so go read the docs here if you still want to know more.

Continued Horribleness

Let’s make a Try in Go.

Since we don’t have generics let’s (for now) just use interface {} as the value contained within our Try.

type Try struct {
    success bool
    value   interface{}
    err     error
}

Pretty self-explanatory. Also note that success is used instead of checking for nil on success or err because it’s more explicit’ish.

Next a utility function.

func ToTry(value interface{}, err error) *Try {
    return &Try{
        success: err == nil,
        value:   value,
        err:     err,
    }
}

Now we can wrap other functions that produce value/err results. Such as:

func doSomething() (string, error) {
    if someCheck() {
        return "biscuits", nil
    }
    return "", errors.New("You failed the all-important check")
}

func main() {
    var result Try = ToTry(doSomething())

    // use result as Try
}

So we got a basic container, but that’s more or less useless. Especially given that there are no publicly exported fields in our struct and no functions except our utility function to create/use the Try. Let’s define some basic functions for creating and interacting with Try:

// NewSuccess creates a new succeeded Try
func NewSuccess(value interface{}) *Try {
    return &Try{
        success: true,
        value:   value,
        err:     nil,
    }
}

func NewFailure(err error) *Try {
    return &Try{
        success: false,
        value:   nil,
        err:     err,
    }
}

func (t *Try) IsSuccess() bool {
    return t.success
}

func (t *Try) IsFailure() bool {
    return !t.success
}

func (t *Try) GetValue() interface{} {
    if t.IsFailure() {
        panic("you do not know what you are doing") // totally right thing to do
    }
    return t.value
}

func (t *Try) GetFailure() error {
    if t.IsSuccess() {
        panic("you do not know what you are doing") // totally right thing to do
    }
    return t.err
}

This is good, but not entirely usable. As it stands this is just as wonderful as the existing Go model of checking errors right at the source. We need some way for the errors to cascade and for us to say what we want to do without having to worry about so much error handling. For this we have to break out the big guns (pew pew), map and flatMap. If you haven’t heard of these functions yet, maybe go try googling “higher order functions” to get a better idea. I’ll avoid explaining them here since that could be a whole other post on it’s own.

Let’s take a stab at this:

func (t *Try) Map(f func(interface{}) interface{}) *Try {
    if !t.success {
        return t
    }
    return &Try{
        success: true,
        value:   f(t.value),
        err:     nil,
    }
}

func (t *Try) FlatMap(f func(interface{}) *Try) *Try {
    if !t.success {
        return t
    }
    return f(t.value)
}

func (t *Try) FlatMapWrap(f func(interface{}) (interface{}, error)) *Try {
    if !t.success {
        return t
    }
    return ToTry(f(t.value))
}

So now with this, we can attempt to chain some stuff together, with all the wonderfulness that is working with interface {} which is obviously the superior way of writing code in Go:

func test()          (string, error) { return "", nil }
func test2(s string) (int, error)    { return 128, nil }
func test3(i int)    *Try            { return NewSuccess(true) }
func test4(b bool) string {
    if b {
        return "true"
    }
    return "false"
}

func main() {
    ToTry(test()).FlatMapWrap(func(s interface{}) (interface{}, error) {
        return test2(s.(string))
    }).FlatMap(func(i interface{}) *Try {
        return test3(i.(int))
    }).Map(func(b interface{}) interface{} {
        return test4(b.(bool))
    })
}

I mean, can you not see the benefit of this yet? Who would not choose this highly readable, soooper maintainable code over immediate error checking? It’s always best to avoid your problems as long as possible (LPT).

Less Horrible?

Even though so far we have a working Try complete with interface {} everywhere (a favorite style of “real programmers”), the benevolent overlords of Go built us go generate and it would be a shame to not find a way to shove that into this blog post.

Thanks to genny, onwards and upwards my friends!

First a template without any of the transformation functions (Map, FlatMap, etc):

package try

import (
	"github.com/cheekybits/genny/generic"
)

type Type generic.Type

type TypeTry struct {
	success bool
	value   Type
	err     error
}

func ToTypeTry(value Type, err error) *TypeTry {
	return &TypeTry{
		success: err == nil,
		value:   value,
		err:     err,
	}
}

func NewTypeSuccess(value Type) *TypeTry {
	return &TypeTry{
		success: true,
		value:   value,
		err:     nil,
	}
}

func NewTypeFailure(err error) *TypeTry {
	return &TypeTry{
		success: false,
		err:     err,
	}
}

func (t *TypeTry) IsSuccess() bool {
	return t.success
}

func (t *TypeTry) IsFailure() bool {
	return !t.success
}

func (t *TypeTry) GetValue() Type {
	if t.IsFailure() {
		panic("you do not know what you are doing")
	}
	return t.value
}

func (t *TypeTry) GetFailure() error {
	if t.IsSuccess() {
		panic("you do not know what you are doing")
	}
	return t.err
}

With this + genny, we can generate some basic Try code for a specific type without any composition functions (we’ll get there). To get the basic support we’d simply run:

# inside the root of your project
mkdir -p try
genny -in try_base.go.tmp -out try/int_base.go gen "Type=int"

And you can now write code like:

var it IntTry = NewIntSuccess(5)
if it.IsSuccess() {
    fmt.Println(it.GetValue())
}

Of course, without being able to compose things with Trys of other types, this isn’t that great. So let’s make a template that allows us to map from one type to another:

package try

import (
	"github.com/cheekybits/genny/generic"
)

type FromType = generic.Type
type ToType = generic.Type

func (t *FromTypeTry) MapToToType(f func(FromType) ToType) *ToTypeTry {
	if !t.success {
		return &ToTypeTry{
			success: false,
			err:     t.err,
		}
	}
	return &ToTypeTry{
		success: true,
		value:   f(t.value),
		err:     nil,
	}
}

func (t *FromTypeTry) FlatMapToToType(f func(FromType) *ToTypeTry) *ToTypeTry {
	if !t.success {
		return &ToTypeTry{
			success: false,
			err:     t.err,
		}
	}
	return f(t.value)
}

func (t *FromTypeTry) FlatMapWrapToToType(f func(FromType) (ToType, error)) *ToTypeTry {
	if !t.success {
		return &ToTypeTry{
			success: false,
			err: t.err,
		}
	}
	return ToToTypeTry(f(t.value))
}

With this I can replace our original genny command with these two:

genny -in try_base.go.tmp    -out try/try_base.go    gen "Type=string,int"
genny -in try_compose.go.tmp -out try/try_compose.go gen "FromType=string,int ToType=string,int"

And now I have two Try types, IntTry and StringTry and can seamlessly convert back and forth like so:

func main() {
	composedValue := try.NewStringSuccess("37").
		FlatMapWrapToInt(strconv.Atoi).
		MapToString(func(i int) string {
			return fmt.Sprintf("Parsed to: %d", i)
		})

	if composedValue.IsSuccess() {
		fmt.Println(composedValue.GetValue())
	}
}

Conclusion

\o/ Yay! This is all very horrible, but it actually works in a usable way. Feel free to spread the love ;-)

github.com/johnmurray/bastard-go/

PS

If you made it all the way to the end and didn’t realize this was written with intentional sarcasm… ¯\_(ツ)_/¯

The Futures Abstraction

Thu, 22 Jun 2017 12:00:00 +0000

Concurrency has many different abstractions: There are the classic processes and threads, the older but newly-new actor-based concurrency, CSP style concurrency (looking at you Go), and the quite popular future/promise. There are more, but one thing they all have in common is the goal to create a better way to achieve concurrent computation. This is great, if we understand what we’re abstracting.

When it comes to futures, there are a great number of articles online about how to get started using a particular implementation/framework for futures. However there is a much smaller number of articles that properly explain what a future is, how they work, and what exactly the abstraction provides you. This article will walk through those details by implementing futures from the ground-up.

Before we jump right into code, what is the definition of future? From Wikipedia we get:

… future, promise, delay, and deferred refer to constructs used for synchronizing program execution in some concurrent programming languages. They describe an object that acts as a proxy for a result that is initially unknown, usually because the computation of its value is yet incomplete.

A future represents the result of some computation, which will eventually yield a result. The “eventually” bit typically implies that there is some computation that is executing asynchronously (in another thread, for example) but can also imply a deferred value. You can think of a deferred value as a lazy value that is not computed until needed. For this article, we will assume that a future is the result of an async computation. Note that different implementations may use the names “future,” “promise,” and “deferred” interchangeably and may differ from this post.

Great! Now that we understand what a future is, let’s build our abstraction from the ground-up.

The Tools

For this post we’ll be using Scala without any any additional libraries and will only be utilizing threads for our concurrency. We’ll also make use of some data-structures for sharing values between threads. Even though I am using Scala, I will avoid any advanced syntax so those unfamiliar can still (hopefully) follow along.

Part 1 - Concurrent Computations

Before we can get into the meat of our abstraction, we need to at least be able to execute some code concurrently, which can be done simply with threads. Using a new thread for each computation looks like:

val concurrentComputation = new Thread(new Runnable {
  def run(): Unit = {
    println("I'm running concurrently! whoop!")
  }
})

concurrentComputation.start()

This is fairly simple, but some things are worth pointing out.

1) Unit means that we didn’t return a value (similar to void in other languages).
2) The Thread object does not start executing the run function until we call start() on line 7.

Despite its simplicity, this is a lot of code to type for each block of code we want to run concurrently. Let’s rewrite this as a function that we can pass a block of code into. For this article, all code will live in the simple.future namespace.

1
2
3
4
5
6
7
8
9
10
11
package simple.future

def future(block: => Unit): Unit = {
  val concurrentComputation = new Thread(new Runnable {
    def run(): Unit = {
      block
    }
  })

  concurrentComputation.start()
}

And we can now call our function like so

future { print("I'm running concurrently! whoop!") }

The Scala bits that may throw you here are

1) block: => Unit is a pass-by-name value that returns a Unit (not executed until called).
2) block on line 6 evaluates the user-provided code within the run method, which is called once the Thread is running.
3) { ... } is a block of code that is passed to future as the first parameter to the function.

Just a quick note on point #1: Pass-by-name means that we can pass around blocks of user-code without actually executing them. Only once we request the “value” from the block (like we do on line 6 above), is the code executed. This is essential for how our futures execute code asynchronously.

Fantastic! Now we just need to somehow return a result and we’re done, right? Well, not exactly. While that would get us pretty close to the initial definition, I want to stay a little more grounded and mimic what a future implementation would do in practice. We’re also missing something from our current function.

In a real, multi-threaded application there are often multiple operations happening at once; many of which may be simultaneously using futures. However, not all futures are equally important. For example, pushing work to a queue that came from a user is arguably more important than flushing metrics to your metrics store. Currently, we create a thread for each future. It is up to the threads to fight it out with the JVM/OS scheduler for resources. A better solution would make use of thread pools.

Thread pools are small groups of threads that work is executed on. If there is more work than threads in the pool, then they are queued up and executed once a thread from the pool is available. We can control priority within our application by creating larger pools for more important, time-sensitive work and smaller pools for less important, less critical work.

Let’s rewrite our future function to work with a Java thread pool!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
package simple.future

import java.util.concurrent.LinkedBlockingQueue
import java.util.concurrent.ThreadPoolExecutor
import java.util.concurrent.TimeUnit

def future(tp: ThreadPoolExecutor)(block: => Unit): Unit = {
  if (tp.isShutdown || tp.isTerminating || tp.isTerminated) {
    throw new RuntimeException(
      "Cannot execute on threadpool that is not active/running.")
  }
  tp.execute(new Runnable {
    def run(): Unit = {
      block
    }
  })
}

val tp = new ThreadPoolExecutor(4, 4, 0L,
                                TimeUnit.MILLISECONDS,
                                new LinkedBlockingQueue[Runnable])
future(tp) { print("I'm running concurrently! whoop!") }

We now have a future function that works with thread pools! To explain some things

1) future has multiple parameter lists (...). This allows us to continue to use the block-syntax for user-provided code { ... }.
2) future now throws a RuntimeException if it is given a ThreadPoolExecutor that is not usable.
3) tp.execute(...) adds work to the thread pool’s queue and runs it asynchronously.
4) tp on line 19 is a thread pool with exactly 4 threads which uses a LinkedBlockingQueue as the backing queue when there is more work than available threads.

Part 2 - Returning the Result

We’re quickly working our way towards a future implementation, but currently we don’t have a way to return a value back to the caller. According to our definition at the beginning, we need to use some sort of “proxy” object that will eventually contain the value. Let’s define what this proxy object could look like.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
package simple.future

class Future[T] {
  private var result: Option[T] = None

  // writer functions
  def write(value: T): Unit = {
    this.result = Some(value)
  }

  // read functions
  def isReady: Boolean = result.isDefined
  def get: T = {
    if (! isReady) {
      throw new RuntimeException(
        "Future is not ready yet, no value to get")
    }
    return result.get
  }
}

Some quick notes

1) [T] is a generic type of T to be determined by the user.
2) Option is a type that is either present (Some) or absent (None).
3) If the future is not completed, we throw an exception on access.

Now that we have our “proxy” object, we can update our future function to return a value using our new Future[T] class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
package simple.future

def future[T](tp: ThreadPoolExecutor)(block: => T): Future[T] = {
  val fut = new Future[T]

  if (tp.isShutdown || tp.isTerminating || tp.isTerminated) {
    throw new RuntimeException(
      "Cannot execute on threadpool that is not active/running.")
  }
  tp.execute(new Runnable {
    def run(): Unit = {
      // call user-provided code and write result to the future
      val result = block
      fut.write(result)
    }
  })

  return fut
}

Some quick notes:

1) The block is now a block of code that evaluates to a type T.
2) future now has type-parameter of T and a return type of Future[T].
3) The value of the Future[T] is written inside the run function.

With this newly updated function, we can still call it the same way. The exception is that it now means something if we capture the result.

val f: Future[String] = future(tp) { "I'm running concurrently! whoop!" }

Awesome! We have our proxy object. But the next question becomes, “How do I use it?” If we wanted to wait on the call we made above for f, we might do something like the following:

val MaxWait = 1000
var i = 0

while (!f.isReady && i < MaxWait) {
  Thread.sleep(5)
  i += 5
}

println(f.get)

This code is far from ideal, but it works for what we want to do. Later on in this article we’ll get to more advanced (and more idiomatic) techniques for working with future values.

However, even though this works, there are two issues with this setup: The first is that anyone can write a value into the future. Ideally this should be hidden as part of the async processing and separated from the Future object. For example, this code should not be valid:

val f: Future[Int] = future(tp) {
  Thread.sleep(1000)  // sleep future for 1s
  5
}
f.write(6)
println(f.get())  // prints 6

// value of f set to 5 1 second later

The second issue is that the value is not immutable. Once it is written, it should not be possible to change the value. As in our example above, once the future stops sleeping, the value would change to 5. A future is always the result of a single computation, and that value must never change.

First let’s address the issue that anyone can write into our Future. The common way this is solved is to introduce another type, called the promise. If a future is meant to read the value, then the promise is meant to write the value. By creating two separate objects, we can hand them to the appropriate parties. Let’s see what this would look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
package simple.future

class Future[T](private val promise: Promise[T]) {
  def isReady: Boolean = promise.isReady
  def get: T = promise.get
}

class Promise[T] {
  private var result: Option[T] = None

  lazy val futurePair: Future[T] = new Future[T](this)

  // writer functions
  def write(value: T): Unit = this.synchronized {
    this.result = Some(value)
  }

  // reader functions
  def isReady: Boolean = this.synchronized { result.isDefined }
  def get: T = this.synchronized {
    if (!isReady) {
      throw new RuntimeException(
        "Future is not ready yet, no value to get")
    }
    result.get
  }
}

With this new version we can see that Future is now just a read-only interface to our new Promise class, and that each future contains a private reference to its Promise pair. The new Promise class is mostly the same as our original Future implementation with two exceptions:

1) A new futurePair value which creates a Future object that is paired with the current Promise object. This is only generated when needed (thus the lazy part).
2) All read and write methods are now contained in this.synchronizedblocks, which synchronizes access to the Promise object. This is good practice for any object that will be accessed from multiple threads.

However, even with this separation of concerns, Promise can be written to more than once. Since we’ve already synchronized our methods (ensuring no concurrent updates), we can add a simple check to solve our problem:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
package simple.future

class Promise[T] {
  private var result: Option[T] = None
  private var isWritten: Boolean = false;

  // writer functions
  def write(value: T): Unit = this.synchronized {
    if (this.isWritten) {
      throw new RuntimeException(
        "Cannot write value. Already written" )
    }
    this.result = Some(value)
    this.isWritten = true
  }

  // other functions ...
}

Part 3 - Handling Failures

We can now return values from futures, but what happens if the computation fails and we throw an exception? How do we handle that? What value is returned for the future?

Well exceptions are easy, we can just use a try-catch block for that, right?

try {
  val f = future(tp) {
    throw new RuntimeException("sorry!")
  }
} catch {
  case t: Throwable => println("whoops! something went wrong")
}

I’m sorry, but no. This is never going to work.

Why you ask? Well, the throw in the above code is actually not called on the current thread. Remember that the code in block is not evaluated until called within the Runnable.run method. It is called asynchronously on another thread — and guess what? That exception will not propagate to the current thread the above code is executing on. What would actually happen is that future f would just never receive a value because Promise.write would never be called.

Well the answer is simple right? Just put the try-catch inside the Runnable.run function that future creates to execute the code block. Well, what if an exception occurs, what value do you return? To handle this, we need to wrap our T value in Future[T] in a success/fail object:

package simple.future

trait Try[T]
case class Success[T](value: T) extends Try[T]
case class Failure[T](throwable: Throwable) extends Try[T]

With these new types, we can now represent the result of a future, previously just T, as a Try[T]. Of course with this, we need to update our read and write functions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package simple.future

class Future[T](private val promise: Promise[T]) {
  def get: Try[T] = promise.get
  // ...
}

class Promise[T] {
  private var result: Option[Try[T]] = None

  def write(value: Try[T]): Unit = // ...

  def get: Try[T] = // ...

  // ...
}

As well as our future function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
package simple.future

def future[T](tp: ThreadPoolExecutor)(block: => T): Future[T] = {
  val promise = new Promise[T]

  // omitted code

  tp.execute(new Runnable {
    def run(): Unit = {
      try {
        // call user-provided code and write result to the future
        val result = block
        promise.write(Success(result))
      } catch {
        case t: Throwable => promise.write(Failure(t))
      }
    }
  })
  return promise.futurePair
}

Now that we are wrapping values into either a success or failure state and capturing any exceptions, we can now write code like:

val f: Future[String] = future(tp) {
  if (scala.util.Random.nextBoolean()) {
    "I'm running concurrently! whoop!"
  } else {
    throw new RuntimeException("We were unlucky... bummer")
  }
}

val MaxWait = 1000
var i = 0
while (!f.isReady && i < MaxWait) {
  Thread.sleep(5)
  i += 5
}

f.get match {
  case Success(value) => println(value)
  case Failure(t)     => t.printStackTrace()
}

Here we are creating a future which may or may not fail, depending on a randomly generated boolean. Once we’ve waited for it to complete, we access the value with get and then use pattern matching (the match keyword and a popular feature of Scala) to either print the returned string or the error trace, depending on the value returned.

Part 4 - Async Access

To recap what we’ve created so far:

A future method that takes a block of code, executes on a thread-pool, and returns a Future.
Future class for reading values, and a Promise for writing values.
Try[T] to represent success and failure values from our asynchronously executed code-block.

This is a good start to creating a realistic implementation of futures. However, there are still some very big holes. Namely, accessing the final value leaves a lot to be desired. Currently to get the value we have to block on the current thread and wait for the future to be completed.

The easy way to not block is to provide callback functions. Callbacks are user-provided blocks of code that are registered with the Future object and called once the Future is ready. We’ll define three functions: onComplete, onSuccessand onFailure. Let’s start first with onComplete:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
package simple.future

class Future[T](private var promise: Promise[T]) {
  // ...

  def onComplete(tp: ThreadPoolExecutor)(f: Try[T] => Unit): Unit = {
    promise.registerOnComplete(tp, f)
  }
}

class  Promise[T] {
  // ...

  var onCompleteHandlers: List[(ThreadPoolExecutor, Try[T] => Unit)] = Nil

  def registerOnComplete(tp: ThreadPoolExecutor, f: Try[T] => Unit): Unit = {
    // add 2-tuple of thread-pool and function to list
    onCompleteHandlers ::= (tp, f)
  }

  def callOnCompletes(value: T): Unit = {
    for (handler <- onCompleteHandlers) {
      val tp: ThreadPoolExecutor = handler._1
      val f:  Try[T] => Unit     = handler._2

      future(tp) {
        f(value)
      }
    }
  }

  def write(value: Try[T]): Unit = this.synchronized {
    if (this.isWritten) {
      throw new RuntimeException(
        "Cannot write value. Already written")
    }
    this.result = Some(value)
    this.isWritten = true
    this.callOnCompletes(value)
  }
}

We now have a new method on Future of onComplete which registers a callback handler with Promise. The reason that Promise handles the firing of the callback is because it maintains the relationship that Future is read-only and that Promise is the write interface. With this, we can fire the callbacks as soon as Promise.write is called.

Some final notes about the above code:

1) onCompleteHandlers is a list of 2-tuples containing the thread pool and the block of code to execute on the result. It is also initialized to an empty list (Nil).
2) The code onCompleteHandlers ::= (tp, f) appends a 2-tuple to the list onCompleteHandlers.
3) Values in 2-Tuples are accessed by x._1 and x._2 as on line 23 and 24.

And we can now use our new function like:

val f: Future[String] = future(tp) {
  if (scala.util.Random.nextBoolean()) {
    "I'm running concurrently! whoop!"
  } else {
    throw new RuntimeException("We were unlucky... bummer")
  }
}

f.onComplete(tp) { res: Try[String] =>
  res match {
    case Success(value) => println(value)
    case Failure(t)     => t.printStackTrace()
  }
}

With this, we could easily imagine how to write other functions such as onSuccess, onFailure, etc.

Part 5 - Composing Futures

Callbacks are an excellent way to access data retrieved/generated from an asynchronous operation. However, what if we wanted to combine the value from two async operations, or we wanted to transform the result of an async operation, but still maintain a future to that transformed value in the current thread? This is where futures really shine: The ability to combine the result of multiple futures together.

To achieve this, we need to have callbacks that return yet another Future as a proxy object to a result of the callback. The first function we’ll look at is map with the following signature:

class Future[T](...) {
  def map[U](tp: ThreadPoolExecutor)(f: T => U): Future[U]
}

map takes a thread pool and a function and returns another future. The user-provided function, f, takes as a parameter a successful value from the current future and returns a value of type U. However map returns a value of type Future[U]. This allows us to call map on a Future that may or may not be completed. This means that we can’t return the result of our transformation (f) directly, but must use another Future. This is best explained with some examples:

// base future we'll be map'ing
val f: Future[Int] = future(tp) {
  Thread.sleep(2000)  // sleep 2 seconds
  2
}

// multiply f by 10
val f10: Future[Int] = f.map(tp) { two => two * 10 }

// turn into a string
val fs: Future[String] = f.map(tp) { two => two.toString }

Because f takes at least 2 seconds to run, you can see why we can’t immediately apply our transformations to the value. Instead we use map to defer the transformations for when the future has completed, but we can still hold onto a proxy object representing the result of those calculations.

But what happens if the future being mapped fails? In that case the error propagates to all failed values:

val f: Future[Int] = future(tp) {
  Thread.sleep(2000)
  throw new RuntimeException("whoops!")
}

val f10: Future[Int] = f.map(tp) { value => value * 10 }

f10.onComplete(tp) { res: Try[Int] =>
  res match {
    case Success(value) => // do nothing
    case Failure(t)     => t.printStackTrace()
  }
}

The above code would print out a stacktrace for f10. The stacktrace would say “whoops!” and would be the same exception from f passed along to f10. This makes sense, as we cannot transform an exception as if it were a successful value.

Enough examples, let’s take a stab at implementing map:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
package simple.future

class Future[T](...) {
  def map[U](tp: ThreadPoolExecutor)(f: T => U): Future[U] = {
    promise.map(tp)(f)
  }
}

class Promise[T] {
  def map[U](tp: ThreadPoolExecutor)(f: T => U): Future[U] = {
    val mapPromise = new Promise[U]
    // create onComplete block that calls user-function (f) on success
    // and passes through exceptions on failure
    val block: Try[T] => Unit = { res: Try[T] =>
      res match {
        case Success(v) => futureWithPromise(tp, mapPromise) {
          f(v)
        }
        case Failure(t) => mapPromise.write(Failure(t))
      }
    }
    registerOnComplete(tp, block)

    return mapPromise.futurePair
  }
}

You can see that we are defining this on Promise. This is because Promise is our writable interface and we want to take advantage of the registerOnCompletefunction we saw earlier. map works by creating a new promise/future pair and returning the future immediately. However the callback that is registered allows us to call our user-provided function f in the callback and write the result to the new promise/future pair we created. For failures we can see the write happening:

  case Failure(t) => mapPromise.write(Failure(t))

This allows us to propagate failure and by-pass the user-provided code which expects a value. This allows us to call map without having to worry about additional error handling.

But wait, what is this futureWithPromise function, and what does it do? Remember future from earlier that takes a block of user code and a thread pool and returns a future? Well this is pretty much the same thing except that it takes a pre-created promise object. With this, we can re-define our future method as well (to avoid duplication) and we get:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
package simple.future

def futureWithPromise[T](tp: ThreadPoolExecutor, promise: Promise[T])
                        (block: => T): Future[T] = {
  if (tp.isShutdown || tp.isTerminating || tp.isTerminated) {
    throw new RuntimeException(
      "Cannot execute on threadpool that is not active/running.")
  }
  tp.execute(new Runnable {
    def run(): Unit = {
      try {
        // call user-provided code and write result to the future
        val result = block
        promise.write(Success(result))
      } catch {
        case t: Throwable => promise.write(Failure(t))
      }
    }
  })

  return promise.futurePair
}

def future[T](tp: ThreadPoolExecutor)(block: => T): Future[T] = {
  val promise = new Promise[T]

  return futureWithPromise(tp, promise)(block)
}

We can see that futuerWithPromise is basically our previous implementation of future and future is now just a convenience method for when you don’t have your own Promise already created.

So much more!

When it comes to composing futures, there is often a myriad of functions available to transform futures in different ways. For example, these two functions are very common (although the naming may differ across implementations):

class Future[T](...) {
  def flatMap[T](tp: ThreadPoolExecutor)(f: T => Future[U]): Future[U]

  def recover(tp: ThreadPoolExecutor)(f: Throwable => T): Future[T]
}

flatMap is very much like our map, but this allows the user-provided code to return a Future[U] instead of just a U. Think of making a web-request which returns a future, and then using the result of the first web-request to make a second web-request. For this case you would use a flatMap.

recover is a way to not only handle a failed future, but also provide/calculate some sort of default value. Imagine making a web-request and, assuming it fails, using recover to provide a cached result. When combining recover with other compositing functions like map and flatMap, we can define a future with all of our transformations and error handling in a declarative way.

Since you’ve seen the basic format for implementing these type of functions (with the map example), I’ll leave it as an exercise to the reader (you) to define flatMap and recover.

Conclusion

That was quite a bit of work! This is still a very bare-bones, basic implementation of futures but, it should be enough to give us some solid ground to stand on for understanding futures, and hopefully understanding why this is a useful (in my humble opinion) and popular abstraction. If you’re interested in what a real-world future implementation looks like, check out some of the links below (note that this post most closely mimics the API of the Scala implementation):

Your Team Should Write SBT Plugins

Fri, 02 Sep 2016 00:00:00 +0000

Every Scala development team should be writing their own SBT plugins. If you’re not then you’re doing it wrong.

This is an ~~assertion~~ assumption I am making based on what I’ve seen so far in my limited experience working on/with various teams and their Scala applications.

Standards

Organizations (not just large ones) typically have standards. Standards for various things including

code style
application packaging
release process
deployment

The list goes on. The general idea however is that if you are building a new application, it should conform to the standards that (ideally) all the other applications in the organization follow.

Now if we’re talking about Scala projects, we have some wonderful tools for defining all of these standards. Specifically I’m talking about SBT. It is the Scala developer’s Swiss army knife. I know that if I start a Scala project today I can use sbt-release for defining my release process (all the steps / actions I take to release my code) which includes essentials standards items such as a versioning scheme. I can also use sbt-native-packager to build deb or rpm packages for Linux or docker images for [insert cloud platform here]. I may also set up my applications with a few useful utilities depending on what I’m writing, such as

scalastyle (and/or sbt-checkstyle if I have some Java code as well)
sbt-reloader (for easy running of my app locally)
sbt-doge (if I’m managing multiple release versions of a lib, or developing an SBT plugin as part of a suite of libraries)
sbt-dependency-graph-sugar (for viewing pretty dep-graphs)

The list goes on. And a lot of it depends on the style or particular flavor of Scala development at each organization.

Maintaining Consistency

So you got your recipe of Scala programming goodness all bundled up in your build.sbt, that’s great! But wait, how do you make sure that other projects use the same data. Well you could just copy it around at first if we’re talking about a handful of applications. Beyond that maybe we make a general template that people clone from to start their projects. But wait, what if the organization decides it wants to add a new step to that sweet release process you wrote using sbt-release? Well, now you need to hop from project to project, updating each build.sbt. And you can’t just copy and paste anymore because you might override some application-specific settings that have built up over time.

There is actually a very simple solution to this problem, organizational SBT plugins. These are plugins that are written for the express purpose of wrapping up all these organizational standards into simple SBT plugins. You have an awesome release process? Great! Wrap that up into an SBT AutoPlugin that uses the sbt-release plugin internally. All that is required for an application to conform to the standard release process is to add a simple addition to their project definition.

project.enablePlugins(OrganizationReleasePlugin)

Using Archetypes

Once you start wrapping this functionality up into your own SBT plugin, you may notice that not all of the applications in your organization fit the same mold. For that we have archetypes. An archetype is a “top-level” AutoPlugin for a particular application type. Archetypes are very much like meta-packages in OS package management systems; it is a collection of AutoPlugins tailored for that specific use case.

For example, a ScalaWebService archetype may contain specific plugins and settings for a PlayFramework application where as a AkkaKernel archetype will have a slightly different set of plugins and settings. Additionally if your organization supports both Java and Scala, you can make those separate archetypes as well to make the provided plugins more tailored toward specific application needs while still maintaining a set of standards for each supported archetype.

Deploying Jekyll to Heroku

Mon, 08 Aug 2016 00:00:00 +0000

So you have a static site in Jekyll that you want to deploy to Heroku. Lucky for you, this is a relatively easy task and does not require anything as complex as a deployment server as mentioned in the Jekyll docs. You can support this with a simple Rack script.

For those not familiar, Rack is a bare-bones web-server adapter in Ruby. Most Ruby web-frameworks sit on “top” of Rack while the Ruby web-servers sit “underneath” of it. However, we don’t need all the complexities of a web-framework to serve our static content, so we only need Rack and any Rack-compatible web-server to accomplish our goals.

Requirements

The bare minimum that you’ll need are

Jekyll site to publish
Your favoriate text editor
Heroku account to push to
Ruby (recent version)
Bundler (gem)

There are a lot of ways to install Ruby so I’ll leave this to you. I will say that I prefer rbenv for its ease of use. Once you have Ruby set up, you can install Bundler via

$ gem install bundle

Gemfile

The first thing we need to declare is all of our runtime requirements for our Rack script that we’ll write later. Put this in a file called Gemfile

source 'https://rubygems.org'

ruby '2.2.0'

gem 'rack-contrib'
gem 'puma'

This file is rather simple, we’re stating the source of our gems (the official repo), the Ruby version (2.2.0) and a couple of gems. The rack-contrib gem will pull in some stuff for static-asset serving (as well as rack itself) and puma is our Rack-compatible web-server.

Once we have our Gemfile we need to create a lock file. This will be used to “lock in” specific versions of gems so that what we try out locally should be exactly the same when we deploy it to Heroku. We can create this with

$ bundle

You should now have a Gemfile.lock in your directory. Do not edit this file.

Rack

Now that we have the required gems installed, we can get down to writing our Rack file that will serve our static assets. Create a file config.ru with the content

require 'rack'
require 'rack/contrib/try_static'

# enable compression
use Rack::Deflater

# static configuration (file path matches reuest path)
use Rack::TryStatic,
      :root => "_site",  # static files root dir
      :urls => %w[/],    # match all requests
      :try => ['.html', 'index.html', '/index.html'], # try these postfixes sequentially
      :gzip => true,     # enable compressed files
      :header_rules => [
        [:all, {'Cache-Control' => 'public, max-age=86400'}],
        [['css', 'js'], {'Cache-Control' => 'public, max-age=604800'}]
      ]

# otherwise 404 NotFound
notFoundPage = File.open('_site/index.html').read
run lambda { |_| [200, {'Content-Type' => 'text/html'}, [notFoundPage]]}

Let’s break this file into the important parts. The first thing we do is import the required gems. This is self explanatory. Next we see

use Rack::Deflater

This bit of code will enable compression on any content that is served. This will speed up your page load time, especially for those with slower internet connections. The next section is the real meat of our Rack file

use Rack::TryStatic,
      :root => "_site",  # static files root dir
      :urls => %w[/],    # match all requests
      :try => ['.html', 'index.html', '/index.html'], # try these postfixes sequentially
      :gzip => true,     # enable compressed files
      :header_rules => [
        [:all, {'Cache-Control' => 'public, max-age=86400'}],
        [['css', 'js'], {'Cache-Control' => 'public, max-age=604800'}]
      ]

This portion defines our static asset handler. The first thing it does is set the “root” of the content directory to _site. This means that if a request comes to /index.html that our static asset handler will look in _site/index.html. Since _site is the default folder for Jekyll auto-generated content, we should be good to go here.

The url defines how we want to match requests. If we wanted to have a Jekyll site as only a sub-section of our site, this would be useful. Since, for the purposes of this example, the Jekyll site comprises the entire web-site we can define this as / to mean the “root” of the web-site.

The try defines various extensions to try when receiving a request. So given what we’ve seen so far, if the application receives a request of /awesome-article it will check for the following files in order

_site/awesome-article
_site/awesome-article.html
_site/awesome-articleindex.html
_site/awesome-article/index.html

With this we can make a variety of requests and get very clean URLs without having to include the .html extensions or without having to specify index when visiting the root of the site (e.g. www.mysite.com).

The gzip and header_rules options simply allow caching to work which we defined earlier. This should help to significantly speed up your site, especially as visitors click from page to page as they will avoid re-loading common resources such as CSS or JS files.

This last part is especially nifty.

# otherwise 404 NotFound
notFoundPage = File.open('_site/index.html').read
run lambda { |_| [200, {'Content-Type' => 'text/html'}, [notFoundPage]]}

This will redirect any request that we can’t understand (broken link or just bad URL) back to the homepage. You could, if you wanted to be really fancy here, provide a custom “Not Found” page. Let your imagination run wild.

Procfile

If we are deploying to Heroku, we need to create a Procfile that tells Heroku how to run our site. We can create a simple file as

web: bundle exec puma -t 5:5 -p ${PORT:-3000} -e ${RACK_ENV:-development}

This instructs Heroku to use our puma gem to run our web-service and some additional parameters that Heroku requires (you can safely ignore these).

Releasing!

We are now ready to push to Heroku! Assuming you’ve already setup your Heroku account and have authenticated in your local repo. We can run the following bit to deploy.

# Add all of the files we've recently created
git add Gemfile Gemfile.lock Procfile config.ru
git commit -m "Adding required files for deploying to Heroku"

# Regnerate your site
rm -rf ./_site
jekyll build

# Add your site to your git repo (important for Heroku to work)
git add ./_site
git commit -m "rebuilt site"

# deploy to heroku via git push (assuming remote for Heroku already setup)
git push heroku master

Personally, I like to put all of this into a Makefile sot that I can automate this process.

default: deploy

deploy:
	rm -rf ./_site
	jekyll build
	git add ./_site
	git commit -m "rebuild of ./_site dir for release"
	git push heroku master

Inspecting JSON From The Command Line

Mon, 25 Jul 2016 00:00:00 +0000

Sometimes you need to inspect some heterogeneous JSON documents. When it comes to working with JSON there are a lot of great libraries out there. However, there aren’t many tools out there that allow me to work with JSON in the shell without resorting to writing small custom bits of Python or Ruby each time. And even this doesn’t always get me as far as I’d like it to without writing larger blocks of Ruby/Python code to dig through large / complex JSON documents.

Given the title of this post, you can see where this is heading. I have created a simple command line utility as a gathering place of functionality for inspecting JSON documents. I’ll show off some features of the tool.

If you want to follow-along with the examples I’m showing, feel free to install the tool from PyPi via

pip install json-inspect

Let’s first make a file test.json to contain some fake JSON data to play with

[
 {
   "facebook": {
     "user": {
       "demographic": {
         "regions": [ {"name": "US"}, {"name": "Kentucky"}, {"name": "Louisville"} ]
       }
     }
   },
   "google": {
     "user": {
       "demographic": {
         "regions": [ {"name": "US"}, {"name": "Kentucky"}, {"name": "Highland Heights"} ]
       }
     }
   }
 },
 {
   "twitter": {
     "user": {
       "demographic": {
         "regions": [ {"name": "UK"}, {"name": "Wales"} ]
       }
     }
   }
 }
]

Frequency

If you are working with JSON data that you do not control (think data integrations) then you sometimes need to compare their specification of the data with the data you are actually receiving. For this we can create a histogram of values based on a search expression.

$ cat test.json | json-inspect histo '[].*.user.demographic.regions.[].name'

[].*.user.demographic.regions.[].name:
Highland Heig   | #########################                          | (1)
US              | ################################################## | (2)
Louisville      | #########################                          | (1)
Kentucky        | ################################################## | (2)
UK              | #########################                          | (1)
Wales           | #########################                          | (1)

Maybe I’m biased, but this is great! I was able to inspect this JSON document with minimal command-line-foo.

Search Paths / Expressions

The heart of the previous example is the search expression. It currently consists of three parts (working on a recursive ** operator) which are

[] - Represents an array (containing objects)
* - Represents all fields within an array
TOKEN - This is a field name within an object

The [] and * tokens will result in all values being processed by the next token in the path. The path itself is delimited by ., so this means that field-names with . in them are not supported.

Values

And if instead of creating charts based on values we instead wanted to extract those values, we can do that as well. An example

$ cat test.json | json-inspect ext "[].*.user.demographic.regions.[].*"
Louisville,Kentucky,US,Highland Heights,Kentucky,US,Wales,UK

We can also control the delimiter to make piping values into other command-line tools easier.

$ cat test.json | json-inspect ext -d '|' "[].*.user.demographic.regions.[].*"
Louisville|Kentucky|US|Highland Heights|Kentucky|US|Wales|UK

Keys

So far we’ve seen inspection tools around the values within JSON, but what if we want to see what keys are available within the JSON document? We can easily pull all keys of a JSON document out with

$ cat test.json | json-inspect keys
facebook.user.demographic.regions.name
google.user.demographic.regions.name
twitter.user.demographic.regions.name

Additionally, we can provide some options which will filter out nulls, empty objects, empty primitives, and empty arrays as -n, -o, -p, and -e respectively. We could introduce some new fields to our "facebook" object to test.

{
 "facebook": {
   "user": {
     "demographic": {
       "regions": [ {"name": "US"}, {"name": "Kentucky"}, {"name": "Louisville"} ]
     },
     "null": null,
     "empty_object": {},
     "empty_array": [],
     "empty_primitives": {
       "string": "",
       "int": 0,
       "float": 0.0
     }
   }
 }
}

Okay, so if you just ran the same command we used earlier, you would see all of these new keys. But we can easily filter some or all of them out with some options. To get back to our original set

$ cat test.json | json-inspect keys -nope
facebook.user.demographic.regions.name
google.user.demographic.regions.name
twitter.user.demographic.regions.name

The Source

This is up on my GitHub under the json-inspect project where you can find more information and documentation. I plan to contribute further to this project as I have need, but if you have ideas for useful features and want to contribute, feel free to open PRs.

Poor Man's Actors in Java

Thu, 31 Mar 2016 00:00:00 +0000

Actors are a fantastic way to model concurrency and a much easier mental model than when working with plain threads and shared memory. However let’s say that you’re writing a very simple library that needs to run some simple background tasks. You could pull in one of the popular Actor implementation libraries out there, but they don’t come for free and can sometimes be heavy-weight.

There is a small movement in the JVM communities to move toward completely self-contained libraries. I am personally in favor of this movement, but it does mean it can make writing libraries a touch more difficult. So, if I’m writing a library and I want to do some async stuff and I really like using actors, what do I do? Well I personally like to program in the actor model (primarily) for two things

Messages are immutable
Message passing as a way of communicating

So the question is, can we get this with zero runtime dependencies? Of course we can, but how much work is it going to be? Let’s find out.

The Exercise

Before we jump right into the meaty bits, we need to setup a problem that our examples will be trying to solve. Let’s say that I’m writing a library that will do some local file-caching. As part of this, the library needs to handle active cache expiry. Active meaning that we don’t wait until the value is read again to do the cleanup, meaning we need some sort of asynchronous monitor.

Immutable Messages

There is nothing stopping from creating immutable data-structures in Java. However it may not be as easy as using say case classes in Scala. However it is most certainly possible. However, this one is pretty easy to get with very little work on our part. Java has long had annotation processors, which is a way to generate code based on annotations at compile time. You can imagine that this is very useful, especially for defining immutable objects. Luckily for us, someone has already went through the work to create a generator for immutable data. If you are not already familiar, meet Immutables.

Let’s define some models that we’ll use later

1
2
3
4
5
6
7
8
9
10
11
@Value.Immutable
public interface CacheCreated {
  Path getFilePath();
  Long getTtl();
  TimeUnit getTtlUnit();
}

@Value.Immutable
public interface CacheExpired {
  Path getFilePath();
}

That’s it! We now have immutable data-objects that are easy to work with. Let’s move on to the Actors.

Actors

Well we already know we have threads for running concurrent operations, but how do we handle the message passing? Simple, we define a mailbox that actors receive messages into and process out of. But what is a mailbox if not just a simple queue. Java has a bunch of those! In fact, there is a nice thread-safe one that works for us, the ConcurrentLinkedQueue. So that means we can define an actor as

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
final ConcurrentLinkedQueue<Object> mailbox = new ConcurrentLinkedQueue<>();

Thread actor = new Thread(() -> {

  while (true) {
    Thread.sleep(10);

    Object msg = mailbox.poll();
    if (msg == null) {
      continue;
    }

    try {
      // process message
    } catch (Exception e) {
      // handle exception(s)
    }
  }

});
actor.start();

Let’s break this down so we understand all that is happening here. First the mailbox

final ConcurrentLinkedQueue<Object> mailbox = new ConcurrentLinkedQueue<>();

All variables used within lambdas or anonymous inner classes must be effective final, thus the final. Note that we are also typing the collection to Object, why? This allows us to send any kind of messages to our actors and the actors can pattern match to find out what the message is. Since we’re in Java, pattern matching really just means doing a bunch of instaceof statements.

while (true) {
  Thread.sleep(10);

To keep the actor alive, the thread cannot end or be “done.” Because of this, we have the thread run in an infinite loop. However we also don’t want our process in a “busy wait.” To get around this we sleep for 10ms at the beginning of each loop. 10ms is arbitrary and is just represents the trade-off between using resources and responding to events in a timely manner.

Object msg = mailbox.poll();
if (msg == null) {
  continue;
}

Attempt to read the first thing in the mailbox (if anything is there). If there is nothing in the mailbox then null is returned. In this case we simply jump back up to the beginning of the infinite loop which causes us to sleep for 10ms before checking again.

Object msg = mailbox.poll();
try {
  // process message
} catch (Exception e) {
  // handle exception(s)
}

For the same reason that we put everything into a while, we also need to catch any errors that might occur. If an exception is thrown, then we need to have code to handle the error and allow the actor to continue processing. Otherwise the exception could crash our thread and effectively kill our actor. Note that supervision is not something our implementation has.

File-Caching Actors

For my system I will define two actors. One actor to receive created events and monitor when cache items should be expired. This actor will send messages to another actor which will take care of the actual file deletion.

Putting what we defined above to good use, I can define my actor as

1
2
final ConcurrentLinkedQueue<Object> ttlWatcherMailbox = new ConcurrentLinkedQueue<>();
final ConcurrentLinkedQueue<Object> cacheDeleterMailbox = new ConcurrentLinkedQueue<>();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
Thread cacheWatcher = new Thread(() -> {
  Map<Path, DateTime> cacheExpiry = new HashMap<>();
  int count = 0;
  while (true) {
    try {
      count++;
      Thread.sleep(10);

      // check for new items to store
      Object msg = ttlWatcherMailbox.poll();
      if (msg == null) break;
      if (msg instanceof CacheCreated) {
        CacheCreated cc = (CacheCreated) msg;
        cacheExpiry.put(cc.getFilePath(), calculateExpiryDate(cc.getTtl(), cc.getTtlUnit());
      } else {
        // log unhandled message
      }

      // scan cached objects (every 100ms, roughly)
      if (count % 10 != 0) continue;
      for( Map.Entry<Path, DateTime> entry : cacheExpiry.iterator() ) {
        if (isExpired(entry.getValue()) {
          cacheDeleterMailbox.offer(ImmutableCacheExpired.builder()
              .filePath(entry.getValue())
              .build());
        }
      }
    } catch (Exception e) {
      // log out errors
    }
  }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Thread cacheDeleter = new Thread(() -> {
  while (true) {
    try {
      Thread.sleep(10);

      Object msg = cacheDeleterMailbox.poll();
      if (msg == null) continue;
      if (msg instanceof CacheExpired) {
        CacheExpired ce = (CacheExpired) msg;
        deleteFile(ce.getFilePath());
      } else {
        // log unhandled message
      }
    } catch (Exception) {
      // log out errors
    }
  }
});

1
2
cacheWatcher.start();
cacheDeleter.start();

Bam! We now have simple actors performing our background jobs and communicate by message passing. We could take this further if wanted and use some of Java’s concurrent blocking queues which would give us back-pressure as well. And like that, there are many small things you could do to add the features that you most value in a full-blown actor framework / library.

Improving our API

If we want to take our working code a little bit further we can improve the current API to abstract some of the details for how this is working. First let’s define a central place to create our actors and store all of our mailboxes. Also, mailboxes should have an address, let’s do this by naming our actors / mailboxes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
class ActorRef {
  private ConcurrentLinkedQueue<Object> mailbox = new ConcurrentLinkedQueue<>();
  private String name;

  public ActorRef(String name) {
    this.name = name;
  }

  public void tell(Object msg) {
    mailbox.offer(msg);
  }

  public Object getLetter() {
    return mailbox.poll();
  }

  public int getLetterCount() {
    return mailbox.size();
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class ActorSystem {
  private Map<String, ActorRef> registry = new HashMap<>();

  public ActorRef actor(String name, Consumer<Object> f) {
    ActorRef ref = new ActorRef(name);
    registry.put(name, ref);

    Thread t = new Thread(() -> {
      while (true) {
        if (ref.getLetterCount() == 0) {
          Thread.sleep(10);
        }
        f.accept(ref.getLetter());
      }
    });
    t.start();

    return ref;
  }

  public Optional<ActorRef> lookup(String name) {
    ActorRef ref = registry.get(name);
    return Optional.of(ref);
  }
}

Modeling this off of Akka, we now have an ActorRef which wraps the mailbox and an ActorSystem that tracks all of the actors in our system and also creates some easier utilities for creating actors. We can now define actors in our system as

1
2
3
4
5
6
7
8
9
ActorSystem system = new ActorSystem();

ActorRef echoActor = system.actor("echo", (Object msg) -> {
  if (msg instanceof String) {
    System.out.println((String) msg);
  }
});

echoActor.tell("Hello, World!");

and we can handle communication between two named actors as

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
ActorSystem system = new ActorSystem();

ActorRef ping = system.actor("ping", (Object msg) -> {
  if (msg instanceof String) {
    String sMsg = (String) msg;
    if (sMsg.equals("ping")) {
      System.out.println("ping");
      system.lookup("pong").ifPresent((ActorRef pong) -> pong.tell("pong"));
    }
  }
}
ActorRef pong = system.actor("pong", (Object msg) -> {
  if (msg instanceof String) {
    String sMsg = (String) msg;
    if (sMsg.equals("pong")) {
      System.out.println("pong");
      system.lookup("ping").ifPresent((ActorRef ping) -> ping.tell("ping"));
    }
  }
}

Sweet! Now we have two actors that can look each other up and communicate back and forth endlessly. Not that this is a useful example, but it shows out our API improvements work.

Of course you can continue adding little improvements like this until you are eventually building a full actor implementation (which you shouldn’t do). So this brings us to our next question.

Should You Do This?

So we’ve seen how we can create some really bare-bones actors but the question really is, “is it worth it?” The answer to this question depends on what you’re doing. If all you need is some very simple concurrency within your library, then this solution is fantastic as it’s zero-dependency. However if you are performing very complex concurrent tasks that require a lot of coordination or cooperation, then using a more full-featured framework may be to your benefit. The title did say this was a “poor man’s” implementation, which means we’re missing many of the feature that would come in a typical actor framework / library.

And actually, if you take a look at Akka (a popular Actor framework on the JVM), you’ll notice that the dependency tree is surprisingly small. So, if you must require all the power of a full-blown actor implementation, at least it’s not bloating your dependency tree too much.

sbt> akka-actor/dependencyGraph

             +-------------------+
             |akka-actor_2.11 [S]|
             | com.typesafe.akka |
             |   2.4-SNAPSHOT    |
             +-------------------+
                |          |
                |          -------------
                |                      |
                v                      v
  +---------------------------+ +------------+
  |scala-java8-compat_2.11 [S]| |   config   |
  |  org.scala-lang.modules   | |com.typesafe|
  |           0.7.0           | |   1.3.0    |
  +---------------------------+ +------------+

Typed PATCH

Sun, 29 Nov 2015 12:00:00 +0000

When building web services we need to define a contract of how the service will operate and how the client should communicate with the service. One important piece to this is the data that the service returns (usually on read operations) and the data the service expects to receive (usually on write operations). One really fantastic way to do this, especially when working in a language like Scala, is to use types.

If I were designing a simple service to manage contacts, I might define my type to look like:

1
2
3
4
5
6
7
case class User(id: Long,
                name:         String,
                birthday:     Date,
                email:        Email,
                address:      Option[Address],
                createdOn:    Date,
                lastModified: Date)

This type accurately represents what I believe a contact, in the context of my API, is defined as. All pieces except address are required and I also expect a few meta-data fields to exist such as id, createdOn and lastModified. This type works great when defining objects in my system, but it starts to break down as a definition for a contract with a consumer of my web-service.

While this works decently well for read operations, where the full object is returned, what does this look like for a create (POST) operation? To start I no longer need any of what I’ll call “system provided” fields such as id, createdOn and lastModified. Some of you might be saying one of two things right about now:

Default the fields to null
Make fields that aren’t required an Option

I’m going to stop you right now. The purpose of this type is supposed to be a way to expose a contract to the user. Making fields that will always exist on reads an Option is really just a lie and not very useful for defining a complete contract. To truly use types as our contract here, we need to define a create-specific type. In our case, it might look like:

1
2
3
4
case class UserCreate(name:     String,
                      birthday: Date,
                      email:    Email,
                      address:  Option[Address])

This gets us where we want to be at the price of having to create and maintain another type in our application.

Now it’s time to think about how we would support operations such as PATCH which are based around the idea of partial edits. Since, by the nature of partial edits, everything is optional you can see that we can’t use the same model that we used for create. Also, since we will need to know the difference between null and absent, we’ll need to use a TriState value to represent any types that are currently nullable (or non-required by our default model).

1
2
3
4
5
case class UserCreate(id:       Long,
                      name:     Option[String],
                      birthday: Option[Date],
                      email:    Option[Email],
                      address:  TriState[Address])

In the above model, we assume Option to be a matter of presence (not nullability) and TriState to represent both presence and nullability.

Ta-da! We now have models that represent create, read, and partial edit. With this, we can now work on optimizing our workflow. I think the proper step is to define an abstract language that can define our service contract and allow our tooling to generate our corresponding models for us. As a matter of fact, this is what we do in Fireglass (an internal web-service framework) used at my current employment.

However, this framework is not (yet, maybe someday) open source. After some quick looking around, I came across an older project that aimed to solve the problem via macros. While I don’t necessarily agree with the approach, it is a solution that is available today.

https://github.com/pathikrit/metarest

Web Service Data Models - Null

Mon, 04 May 2015 12:00:00 +0000

This relates to my other post “Typed Actions In Play”. You may want to skim it to understand my aim in all this madness.

I’m on quest. I am attempting to create some abstractions that allow me to work solely with well-typed models for the purpose of developing web services. I am primarily working in JSON which means I just need to come up with a sound data-model for the JSON that I expect to send/receive to/from the web-service clients. Sounds like a fairly easy task, yes? Well, sadly it is not.

Living with Null

Null values in JSON are a very interesting thing to represent in Scala. While Scala does have the concept of null, it seems primarily as a way to survive interop with Java, where using null is very common. However the conventional wisdom in the Scala community is to replace null with Option[T] for some type T that is null‘able. T can then be represented as Some[T] or None. This makes a lot of sense, but it fails to meet the requirements for JSON in the context of web services, and we’ll see why.

Let’s assume that we’re going to build a service to manage users. The JSON to represent a user may look like this

1
2
3
4
5
{
  "name": "John Murray",
  "email": "my-email@gmail.com",
  "userName": "johnmurray_io"
}

Let’s assert that the userName can be, in the JSON, either a string value or a null value. Let’s further assert that if the user does not provide this in the POST JSON that it defaults to a null value.

For editing the object, let’s assume that we accept partial edits over PUT and/or PATCH (depending on which philosophy you subscribe to). This means that I do not have to supply the full JSON object, only the fields that I wish to edit. This is a very common practice in web services.

If I were only looking at the requirements for object creation, then I might define my model like so

1
case class User(name: String, email: String, userName: Option[String])

and the previous data would translate into

1
User("John Murray", "my-email@gmail.com", Some("johnmurray_io"))

However, this model does not meet all of our requirements, only those for object creation. Specifically what happens when I send in the following, partial update

1
2
3
4
{
  "name": "John M. Murray",
  "email": "my-other-email@gmail.com"
}

This translates into our model as being

1
User("John M. Murray", "my-other-email@gmail.com", None)

You can easily see where the breakdown is. Because we do not have a value for the userName it has no other choice than to be None. We are conflating the absence of a value with the value being null. In the case that the value is absent on an edit operation, the user does not intend to edit the field. This means that we cannot reliably set the userName field to an empty value, ever. To solve this we can introduce the TriState[T] type.

Introducing the TriState[T]

As we have seen, we are in need of a type that can represent more than the two states provided by Option[T]. To handle this, we’re going to introduce a new type called TriState[T] whose name we’re borrowing from the world of electrical engineering. See this article on three-state-logic for more details.

1
2
3
4
5
6
trait TriState[T]
object TriState {
  case class Present[T](value: T) extends TriState[T]
  case class Absent extends TriState[Nothing]
  case class Null extends TriState[Nothing]
}

If we now replace the type of userName of Option[T] with TriState[T], we can properly represent the edit JSON in our model as:

1
User("John M. Murray", "my-other-email@gmail.com", TriState.Absent)

From this, we know not to edit the field, since it is absent. Additionally if I were to provide a null value on edit, we would know to set the userName to null/empty within our persistent storage solution. From this we can see that Option, for web services, is better replaced with a TriState.

Typed Actions in Play

Tue, 28 Apr 2015 12:00:00 +0000

This is just something I was playing around with when discussing how to build proper tooling for our teams at work. Play has the idea of an Action which is basically a function that takes a Request object and returns a Result object. Each of those can be parameterized for the content type being transmitted.

However, when you’re working in an API, you typically work with some exchange format (e.g. JSON) and then serialize and de-serialize to/from your internal data model. If you are using Scala, then possibly some case classes. Rather than having to worry about the exchange format, developers should really just worry about these data-models when writing their code.

So, just the result of me playing with the idea for a few minutes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
object TypedAction {
  def TypedAction[A,B](f: A => B)(implicit reader: Reads[A], writer: Writes[B]) : Action[String] =
    Action.async(BodyParsers.parse.tolerantText) { request =>
      val json = Json.parse(request.body)
      Future.successful {
        val badRequest: Result = Results.BadRequest("Could not parse input")
        json.asOpt[A](reader).map(f).map(Json.toJson(_)(writer)).map(_.toString()).map(Results.Ok(_)).getOrElse(badRequest)
      } : Future[Result]
    }

  def TypedAction[B](f: () => B)(implicit writer: Writes[B]): Action[String] =
    Action.async(BodyParsers.parse.tolerantText) { request =>
      Future.successful {
        Results.Ok(Json.toJson(f())(writer).toString)
      }
    }
}

And then using the model

1
2
3
4
5
6
case class UserModel(id: Int, name: String)

object UserModel {
  implicit val reads = Json.reads[UserModel]
  implicit val writes = Json.writes[UserModel]
}

We can create a controller that looks like

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
object UserController extends Controller {

  var userStore = Map(
    1 -> UserModel(1, "Joe Schmoe"),
    2 -> UserModel(2, "Susy Jane"),
    3 -> UserModel(3, "Jenny Jackson")
  )

  def getUser(id: Int) = TypedAction[UserModel] { () =>
    userStore(id)
  }

  def storeUser = TypedAction[UserModel, UserModel] { userIn =>
    val nextKey = userStore.keys.max + 1
    userStore += nextKey -> userIn
    userIn.copy(id = nextKey)
  }

}

We could also create different input and output models within the same controller method. In addition, if you really wanted to do something like this you would need to handle errors much better, both from the user code and from the parsing code. I’m also not really doing anything with the Action.async portion above, so that could be improved as well.

But yeah, just some (light) food for thought.

Jenkins EnvVar Templating

Mon, 27 Apr 2015 12:00:00 +0000

I’ve been doing a bit of Jenkins plugin development lately and I have found that documentation can be a bit scarce. Like many projects out there, they show you how to drive a nail and then expect you to go off and build a house. I’m posting a little bit of what I have created in hopes of either sharing some much needed documentation or being shown a better way to do things.

While building my plugin I needed a way to inject Jenkins environment variables, called EnvVars in Jenkins API into some input. Not being able to find any built-in utilities to do this, I wrote my own. So, without further to-do, a util that has been useful (for met at least):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
import hudson.EnvVars;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class EnvTemplater {

    private static final Pattern VARIABLE_PATTERN = Pattern.compile(
            "(\\$\\{?[A-Za-z_]+\\}?)");
    private static final Pattern VARIABLE_NAME_PATTERN = Pattern.compile("([A-Za-z_]+)");

    /**
     * Given an input string, find environment var patterns and inject them into
     * the string from the current environment variables. The input of the string really
     * isn't important to this function, only the format of the variables within the string.
     * We look for two forms of variables:
     *  - $VAR_NAME
     *  - ${VAR_NAME}
     *
     * Note: The environment variables that we are using are not _true_ environment
     * variables, but rather Jenkins Environment variables (the same ones you would normally
     * use to template within a normal Jenkins job).
     *
     * @param input The input string to be templated (possibly containing variable
     *              expressions)
     * @param vars  The vars to use to inject into the input string
     * @return      A string where the variables have been replaced by Jenkins evn variable
     *              value, if the variable exists.
     */
    public static String templateString(String input, EnvVars vars) {
        if (vars == null || input == null) {
            return input;
        }

        String output = input;
        Matcher match = VARIABLE_PATTERN.matcher(input);
        int replacementOffset = 0;

        // iterate through all of the variables that we find
        while (match.find()) {

            // find the variable name (without the $ and {} characters)
            String matchGroup = match.group();
            Matcher varNameMatcher = VARIABLE_NAME_PATTERN.matcher(matchGroup);
            while (varNameMatcher.find()) {
                // pull out variable name, replace using bounds of outer `match`
                String varNameMatchGroup = varNameMatcher.group(1);
                int startPos = match.start(1);
                int endPos = match.end(1);
                if (vars.containsKey(varNameMatchGroup)) {
                    String replacement = vars.get(varNameMatchGroup, matchGroup);
                    output = output.substring(0, replacementOffset + startPos)
                            + replacement
                            + output.substring(replacementOffset + endPos, output.length());

                    // replacement offset is used during string replacement to account for
                    // the string growing or shrinking as we replace values (and the regex
                    // positions being out of date).
                    replacementOffset +=  replacement.length() - (endPos - startPos);
                }
            }
        }
        return output;
    }
}