aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2019-09-28 15:40:41 +0200
committerLoïc Hoguin <[email protected]>2019-09-28 15:40:41 +0200
commitcf84f59d9bdf819d943b3de8e3bc85c561f88efe (patch)
treeaa06efaba01ff939865797892c22f753b17ffe2d /doc/src
parent7bccad4d21b56837a1d9ded905b53800558ead8e (diff)
downloadcowboy-cf84f59d9bdf819d943b3de8e3bc85c561f88efe.tar.gz
cowboy-cf84f59d9bdf819d943b3de8e3bc85c561f88efe.tar.bz2
cowboy-cf84f59d9bdf819d943b3de8e3bc85c561f88efe.zip
Add persistent_term support to the router
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/guide/routing.asciidoc26
-rw-r--r--doc/src/manual/cowboy_router.asciidoc5
2 files changed, 29 insertions, 2 deletions
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