From cf84f59d9bdf819d943b3de8e3bc85c561f88efe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sat, 28 Sep 2019 15:40:41 +0200
Subject: Add persistent_term support to the router

---
 doc/src/guide/routing.asciidoc        | 26 +++++++++++++++++++++++++-
 doc/src/manual/cowboy_router.asciidoc |  5 ++++-
 2 files changed, 29 insertions(+), 2 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/guide/routing.asciidoc b/doc/src/guide/routing.asciidoc
index e5f8c33..9e2ef25 100644
--- a/doc/src/guide/routing.asciidoc
+++ b/doc/src/guide/routing.asciidoc
@@ -210,13 +210,34 @@ Dispatch = cowboy_router:compile([
     %% {HostMatch, list({PathMatch, Handler, InitialState})}
     {'_', [{'_', my_handler, #{}}]}
 ]),
-%% Name, NbAcceptors, TransOpts, ProtoOpts
+%% Name, TransOpts, ProtoOpts
 cowboy:start_clear(my_http_listener,
     [{port, 8080}],
     #{env => #{dispatch => Dispatch}}
 ).
 ----
 
+=== Using persistent_term
+
+The routes can be stored in `persistent_term` starting from
+Erlang/OTP 21.2. This may give a performance improvement when
+there are a large number of routes.
+
+To use this functionality you need to compile the routes,
+store them in `persistent_term` and then inform Cowboy:
+
+[source,erlang]
+----
+Dispatch = cowboy_router:compile([
+    {'_', [{'_', my_handler, #{}}]}
+]),
+persistent_term:put(my_app_dispatch, Dispatch),
+cowboy:start_clear(my_http_listener,
+    [{port, 8080}],
+    #{env => #{dispatch => {persistent_term, my_app_dispatch}}}
+).
+----
+
 === Live update
 
 You can use the `cowboy:set_env/3` function for updating the dispatch
@@ -228,3 +249,6 @@ Dispatch = cowboy_router:compile(Routes),
 cowboy:set_env(my_http_listener, dispatch, Dispatch).
 
 Note that you need to compile the routes again before updating.
+
+When using `persistent_term` there is no need to call this function,
+you can simply put the new routes in the storage.
diff --git a/doc/src/manual/cowboy_router.asciidoc b/doc/src/manual/cowboy_router.asciidoc
index 61b8d57..d3c1306 100644
--- a/doc/src/manual/cowboy_router.asciidoc
+++ b/doc/src/manual/cowboy_router.asciidoc
@@ -13,7 +13,10 @@ The router takes the `dispatch` rules as input from the
 middleware environment. Dispatch rules are generated by
 calling the
 link:man:cowboy_router:compile(3)[cowboy_router:compile(3)]
-function.
+function. The environment can contain the rules directly
+or a tuple `{persistent_term, Key}`, in which case Cowboy
+will call `persistent_term:get(Key)` to retrieve the
+dispatch rules.
 
 When a route matches, the router sets the `handler` and
 `handler_opts` middleware environment values containing
-- 
cgit v1.2.3