Good times with F# by Mark Seemann
Some operations take time to perform, and you may want to capture that information. This post describes one way to do it.
Occasionally, you may find yourself in the situation where your software must make a decision based on how much time it has left. Is there time to handle one more message before shutting down? How much time did the last operation take? What was the time when it started?
It can be tempting to simply use DateTime.Now or DateTimeOffset.Now, but the problem is that it couples your code to the machine clock. It also tends to interleave timing logic with other logic, so that it becomes difficult to vary these independently. Incidentally, it also tends to make it difficult to unit test the time-dependent code.
Timed<'a> #
One alternative to DateTimeOffset.Now that I've recently found useful is to define a Timed<'a> generic type, like this:
type Timed<'a> = { Started : DateTimeOffset Stopped : DateTimeOffset Result : 'a } member this.Duration = this.Stopped - this.Started
A value of Timed<'a> not only carries with it the result of some computation, but also information about when it started and stopped. It also has a calculated property called Duration, which you can use to examine how long the operation took.
Untimed transformations #
Timed<'a> looks like a standard monadic type, and you can also implement standard Bind and Map functions for it:
module Untimed = let bind f x = let t = f x.Result { t with Started = x.Started } let map f x = { Started = x.Started; Stopped = x.Stopped; Result = f x.Result }
Notice, though, that these functions only transforms the Result (and, in the case of Bind, Stopped), but no actual time measurement is taking place; that's the reason I put both functions in a module called Untimed.
In the case of the Bind function, the time measurement is implicitly taking place when the f function is executed, because it returns a Timed<'b>. In the Map function, on the other hand, no time measurement takes place at all. The function simply maps Result from one value to another using the f function.
So far, I've found no use for the Bind function, and only occasional use for the Untimed.map function. What really matters, after all, is to measure time.
Timing functions #
Ultimately, Timed<'a> is only interesting if you measure the time computations take. Here are a few functions I've found useful to do that:
module Timed = let capture clock x = let now = clock() { Started = now; Stopped = now; Result = x } let map clock f x = let result = f x.Result let stopped = clock () { Started = x.Started; Stopped = stopped; Result = result }
Notice that both functions take a clock argument. This is a function with the signature unit -> DateTimeOffset, enabling the capture and map functions to get the time. As the name indicates, the capture function is used to capture a value and 'promote' it to a Timed<'a> value. This value can subsequently be used with the map function to measure the time it took to exectute the f function.
Clocks #
Using the computer's clock is easy:
let machineClock () = DateTimeOffset.Now
As you can tell, this function returns the value of DateTimeOffset.Now every time it's invoked.
You can also implement other clocks, e.g. for unit testing purposes. Here's one (not particularly Functional) way of doing it:
let qlock (q : System.Collections.Generic.Queue<DateTimeOffset>) () = q.Dequeue()
Obviously, since this clock is based on a Queue, I decided to call it qlock. Using that, you can define an easier-to-use function based on a sequence of DateTimeOffset values:
let seqlock (l : DateTimeOffset seq) = qlock (System.Collections.Generic.Queue<DateTimeOffset>(l))
Here's a fake clock that counts up all the days before Christmas in December (so obviously, I had to name it xlock):
let xlock = [1 .. 24] |> List.map (fun d -> DateTimeOffset(DateTime(2014, 12, d))) |> seqlock
The first time you execute xlock:
(xlock ()).ToString("d")
you get "01.12.2014", the next time you get "02.12.2014", the third time "03.12.2014", and so on.
Such fake clocks are mostly useful for testing, but you could also use them to perform simulations in accelerated time - or perhaps even move time backwards! (Last time I used it, WorldWide Telescope enabled you to look at the solar system in accelerated time. I don't know how that feature is implemented, but it sounds like a good case for a custom clock. The point of this digression is that depending on your application's need, being able to manipulate time may not be as exotic as it first sounds.)
Measuring the time of execution #
These are all the building blocks you need to measure the time it takes to perform an operation. There are various ways to do it, but given a clock of the type unit -> DateTimeOffset, you can close over the clock like this:
let time f x = x |> Timed.capture clock |> Timed.map clock f
The time function has the type ('a -> 'b) -> 'a -> Timed<'b>, so, if for example you have a function called readCustomerFromDb of the type int -> Customer option, you can time it like this:
let c = time readCustomerFromDb 42
This might give you a result like this:
{Started = 17.12.2014 11:24:38 +01:00;
Stopped = 17.12.2014 11:24:39 +01:00;
Result = Some {Id = 42; Name = "Foo";};}
As you can tell, the result of querying the database for customer 42 is the customer data, as well as information about when the operation started and stopped.
Concluding remarks #
The nice quality of Timed<'a> is that it decouples timing of operations from the result of those operations. This enables you to compose functions without explicitly having to consider how to measure their execution times.
It also helps with unit testing, because if you want to test what happens in a function if a previous function ran on a Sunday, or if it took more than three seconds to run, you can simply create a value of Timed<'a> that captures that information:
let c' = { Started = DateTimeOffset(DateTime(2014, 12, 14, 11, 43, 11)) Stopped = DateTimeOffset(DateTime(2014, 12, 14, 11, 43, 15)) Result = Some { Id = 1337; Name = "Ploeh" } }
This value can now be used in a unit test to verify the behaviour in that particular case.
In a future post, I will demonstrate how to compose more complex time-sensitive behaviour using Timed<'a> and the associated modules.
This post is number 17 in the 2014 F# Advent Calendar.
Update 2017-05-25: A more recent treatment, including a more realistic usage scenario, is available in the article Type Driven Development.
