pedestal/pedestal — pull request #299 by rkneufeld (2014-11-30 19:36:50+00:00)
Title: Make requests lazy

Afternoon @ohpauleez!

I've largely finished implementing lazy request objects, and I wanted to solicit your feedback. `LazyRequest` now exists and it's functionality largely mirrors that of traditional maps.

## Differences from regular maps:

* `LazyRequest`s *are not* equal to the equivalent regular maps (even if the underlying map is identical). It turns out to be quite tricky (if not impossible) to get commutative equality, and even if you accomplish that, the semantics of equality are open for interpretation.
* To that end, `LazyRequest` implements `RawAccess` and `LazyDatastructure` protocols, which provide `raw`, `touch`, and `realized` methods on `LazyRequest`s.
* `raw` returns the underlying map of an advanced data structure.
* `touch` forces all delays in the underlying data structure to be eagerly realized.
* `realized` returns a fully-realized, plain map.
* Iterating over a `LazyRequest` yields a sequence of `DerefingMapEntry`s (implementing `IMapEntry`). Just like `LazyRequest`'s `get`, a derefing map entry will defer realization of a key-value pair's value until it is explicitly accessed.
* `DerefingMapEntry` is not as close a match to `MapEntry` as `LazyRequest` is to `IPersistentHashMap`. `MapEntry` inherets a good deal of functionality from `AMapEntry`, which did not seem worth the effort unless it is absolutely necessary.

## Changes to `servlet-interceptor`

For the most part, `lazy-request` integrates quite cleanly to `io.pedestal.http.impl.servlet-interceptor`. The most notable omission, is that I have (for the moment) removed the transient/persistent bracketing around `request-map`'s more complicated `add-*` invocations.

Rather than jumping straight to complicating `LazyRequest` by implementing transient/persistent conversions, I wanted to check with you on the necessity of this optimization.

**Do we have any harnesses for measuring the performance gain/loss here? Similarly, it would be nice to benchmark `LazyRequest`s effect on existing applications.**