Perf page

doc/SUMMARY.md

@@ -9,14 +9,15 @@
     * [Route data](basics/route_data.md)
     * [Route conflicts](basics/route_conflicts.md)
 * [Advanced](advanced/README.md)
-    * [Route Validation](advanced/route_validation.md)
-    * [Different Routers](advanced/different_routers.md)
     * [Configuring routers](advanced/configuring_routers.md)
+    * [Different Routers](advanced/different_routers.md)
+    * [Route Validation](advanced/route_validation.md)
 * [Ring](ring/README.md)
     * [Ring-router](ring/ring.md)
     * [Dynamic extensions](ring/dynamic_extensions.md)
     * [Data-driven Middleware](ring/data_driven_middleware.md)
     * [Parameter coercion](ring/parameter_coercion.md)
     * [Compiling middleware](ring/compiling_middleware.md)
+* [Performance](performance.md)
 * TODO: Swagger & OpenAPI
 * TODO: Interceptors

doc/advanced/README.md

@@ -1,5 +1,5 @@
 # Advanced
 
-* [Route Validation](route_validation.md)
-* [Different Routers](different_routers.md)
 * [Configuring routers](configuring_routers.md)
+* [Different Routers](different_routers.md)
+* [Route Validation](route_validation.md)

doc/performance.md

@@ -0,0 +1,63 @@
+# Performance
+
+There are many great routing libraries for Clojure(Script), but not many are optimized for perf. Reitit tries to be both great in features and really fast. Originally the routing was adopted from [Pedestal](http://pedestal.io/), but it has been since mostly rewritten.
+
+### Rationale
+
+* Multiple routing algorithms, select for for a given route tree
+* Route flattening and re-ordering
+* Managed mutability over Immutability
+* Precompute/compile as much as possible (matches, middleware, routes)
+* Use abstractions that enable JVM optimizations
+* Use small functions to enable JVM Inlining
+* Protocols over Multimethods
+* Records over Maps
+* Always be measuring
+* Don't trust the (micro-)benchmarks
+
+### Performance guides
+
+As a library user, some things related to performance:
+
+* avoid wildcard-routes - it's an order of magnitude slower to match than non-wildcard routes
+* it's ok to mix non-wildcard and wildcard routes in a same routing tree as long as you don't disable the [conflict resolution](basics/route_conflicts.md) => if no conflicting routes are found, a `:mixed-router` can be created, which collects all non-wildcard routes into a separate fast subrouter.
+
+### Example
+
+The routing sample taken from [bide](https://github.com/funcool/bide) perf suite, run with a Late 2013 MacBook Pro, with the `perf` profile:
+
+```clj
+(require '[reitit.core :as r])
+(require '[criterium.core :as cc])
+
+(def routes
+  (r/router
+    [["/auth/login" :auth/login]
+     ["/auth/recovery/token/:token" :auth/recovery]
+     ["/workspace/:project/:page" :workspace/page]]))
+
+;; Execution time mean : 3.488297 µs -> 286M ops/sec
+(cc/quick-bench
+  (dotimes [_ 1000]
+    (r/match-by-path routes "/auth/login")))
+
+;; Execution time mean : 692.905995 µs -> 1.4M ops/sec
+(cc/quick-bench
+  (dotimes [_ 1000]
+    (r/match-by-path routes "/workspace/1/1")))
+```
+
+### Is that good?
+
+Based on some [quick tests](https://github.com/metosin/reitit/tree/master/perf-test/clj/reitit), the first lookup is order of 100 times faster than other tested Clojure routing libraries. The second being 3-18x faster. But as like most microbenchmarks, test usually lie as they might test things with different libs. For example, Pedestal also matches on the `:request-method` which makes it do more work. With real life routing trees, the differences are most likely more subtle, or even the order might be totally different.
+
+### So why test?
+
+Real value of perf tests is to have a internal baseline and optimize against it. Also, to ensure that new features don't regress the performance.
+
+It might be interesting to look out of the box and compare Clojure routing libs to routers in other languages, like the [routers in Go](https://github.com/julienschmidt/go-http-routing-benchmark).
+
+### Plans ahead
+
+Currently, the non-wildcard routes are already really fast to match, but wildcard routes use only a naive linear scan. Plan is to add a optimized [Trie](https://en.wikipedia.org/wiki/Trie)-based router. See
+[httprouter](https://github.com/julienschmidt/httprouter#how-does-it-work) and [Pedestal](https://github.com/pedestal/pedestal/pull/330) for details. New routing algorithms can be plugged in easily, without changes in the public apis.

perf-test/clj/reitit/perf_test.clj

@@ -11,7 +11,8 @@
             [io.pedestal.http.route.definition.table :as table]
             [io.pedestal.http.route.map-tree :as map-tree]
             [io.pedestal.http.route.router :as pedestal]
-            [io.pedestal.http.route :as route]))
+            [io.pedestal.http.route :as route]
+            [reitit.core :as r]))
 
 ;;
 ;; start repl with `lein perf repl`
@@ -70,80 +71,89 @@
 
   (suite "static route")
 
-  ;; 2.2µs
+  ;; 1800 µs
   (title "bidi")
   (let [call #(bidi/match-route bidi-routes "/auth/login")]
     (assert (call))
     (cc/quick-bench
-      (call)))
+      (dotimes [_ 1000]
+        (call))))
 
-  ;; 1.5µs (-40%)
+  ;; 1400 µs
   (title "ataraxy")
   (let [call #(ataraxy/matches ataraxy-routes {:uri "/auth/login"})]
     (assert (call))
     (cc/quick-bench
-      (call)))
+      (dotimes [_ 1000]
+        (call))))
 
-  ;; 1.1µs (-50%)
+  ;; 1200 µs
   (title "pedestal - map-tree => prefix-tree")
   (let [call #(pedestal/find-route pedestal-router {:path-info "/auth/login" :request-method :get})]
     (assert (call))
     (cc/quick-bench
-      (call)))
+      (dotimes [_ 1000]
+        (call))))
 
-  ;; 1.5µs (-40%)
+  ;; 1400 µs
   (title "compojure-api")
   (let [call #(compojure-api-routes {:uri "/auth/login", :request-method :get})]
     (assert (call))
     (cc/quick-bench
-      (call)))
+      (dotimes [_ 1000]
+        (call))))
 
-  ;; 11.5ns (-99,5%)
+  ;; 3.5 µs (300-500x)
   (title "reitit")
   (let [call #(reitit/match-by-path reitit-routes "/auth/login")]
     (assert (call))
     (cc/quick-bench
-      (call))))
+      (dotimes [_ 1000]
+        (call)))))
 
 (defn routing-test2 []
 
   (suite "wildcard route")
 
-  ;; 15.4µs
+  ;; 12800 µs
   (title "bidi")
   (let [call #(bidi/match-route bidi-routes "/workspace/1/1")]
     (assert (call))
     (cc/quick-bench
-      (call)))
+      (dotimes [_ 1000]
+        (call))))
 
-  ;; 2.9µs (-81%)
+  ;; 2800 µs
   (title "ataraxy")
   (let [call #(ataraxy/matches ataraxy-routes {:uri "/workspace/1/1"})]
     (assert (call))
     (cc/quick-bench
-      (call)))
+      (dotimes [_ 1000]
+        (call))))
 
-  ;; 2.4µs (-84%)
+  ;; 2300 µs
   (title "pedestal - map-tree => prefix-tree")
   (let [call #(pedestal/find-route pedestal-router {:path-info "/workspace/1/1" :request-method :get})]
     (assert (call))
     (cc/quick-bench
-      (call)))
+      (dotimes [_ 1000]
+        (call))))
 
-  ;; 3.8µs (-75%)
+  ;; 3800 µs
   (title "compojure-api")
   (let [call #(compojure-api-routes {:uri "/workspace/1/1", :request-method :get})]
     (assert (call))
     (cc/quick-bench
-      (call)))
+      (dotimes [_ 1000]
+        (call))))
 
-  ;; 1.0µs (-94%)
-  ;; 690ns (-96%)
+  ;; 710 µs (3-18x)
   (title "reitit")
   (let [call #(reitit/match-by-path reitit-routes "/workspace/1/1")]
     (assert (call))
     (cc/quick-bench
-      (call))))
+      (dotimes [_ 1000]
+        (call)))))
 
 (defn reverse-routing-test []