aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy.set_env.asciidoc
blob: fc0d1f7472df1b04d5752f9c3dc47b1bdfcbd3d6 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
= cowboy:set_env(3)

== Name

cowboy:set_env - Update a listener's environment value

== Description

[source,erlang]
----
set_env(Name  :: ranch:ref(),
        Key   :: atom(),
        Value :: any())
    -> ok
----

Set or update an environment value for a previously started
listener.

This is most useful for updating the routes dynamically,
without having to restart the listener.

The new value will only be available to new connections.
Pre-existing connections will still use the old value.

== Arguments

Name::

The name of the listener to update.
+
The name of the listener is the first argument given to the
link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] or
link:man:ranch:start_listener(3)[ranch:start_listener(3)] function.

Key::

The key in the environment map. Common keys include `dispatch`
and `middlewares`.

Value::

The new value.
+
The type of the value differs depending on the key.

== Return value

The atom `ok` is returned on success.

An `exit:badarg` exception is thrown when the listener does
not exist.

== Changelog

* *1.0*: Function introduced.

== Examples

.Update a listener's routes
[source,erlang]
----
Dispatch = cowboy_router:compile([
    {'_', [
        {"/", toppage_h, []},
        {"/ws", websocket_h, []}
    ]}
]),

cowboy:set_env(example, dispatch, Dispatch).
----

== See also

link:man:cowboy(3)[cowboy(3)],
link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
link:man:cowboy:get_env(3)[cowboy:get_env(3)],
link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)]