async_listen/
errors.rs

1//! # Documentation of the Error Hints
2//!
3//! This page is the destination of the links shown by
4//! [`error_hint`](../fn.error_hint.html).
5//!
6//! List of errors having a hint:
7//!
8//! * [Too many open files](#EMFILE) / [EMFILE](#EMFILE)
9//! * [Too many open files in system](#ENFILE) / [ENFILE](#ENFILE)
10//!
11//!
12//! # Too Many Open Files <a name='EMFILE'></a>
13//!
14//! | Posix Name | EMFILE |
15//! |---|---|
16//! | Message | `Too many open files (os error 24)` |
17//! | Hint | `Increase per-process open file limit` |
18//! | Link | `https://bit.ly/async-err#EMFILE` |
19//!
20//! ## Common Causes
21//!
22//! 1. File descriptor limit for the process is too low
23//! 2. Limit of number of simultaneous connections is either too high or
24//!    unimplemented
25//!
26//! The (2) can be fixed by applying [`backpressure`] abstraction from this
27//! crate.
28//!
29//! The rest of this section discusses how to change file decriptor limit.
30//!
31//! [`backpressure`]: ../backpressure/fn.new.html
32//!
33//! ## Choosing a Limit
34//!
35//! There is no one good strategy. But here are few hints:
36//!
37//! 1. It must be lower than limit on simultaneous connections.
38//! 2. Sometimes it's several times lower, like if you need to open a file
39//!    or to open a backend connection for each client, it should be 2x lower
40//!    plus some offset.
41//! 3. Measure an average memory used by each client and divide memory
42//!    available by that value.
43//!
44//! We use `10000` as an example value later in the text.
45//!
46//! ## Linux
47//!
48//! Either use `ulimit -n` in the same shell:
49//! ```console
50//! $ ulimit -n 10000
51//! $ ./your_app
52//! ```
53//!
54//! If you get the error, you need superuser privileges:
55//! ```console
56//! $ ulimit -n 10000
57//! ulimit: value exceeds hard limit
58//! $ sudo -s
59//! # ulimit -n 10000
60//! # su your_user
61//! $ ./your_app
62//! ```
63//!
64//! On most systems there is `/etc/security/limits.conf` to make persistent
65//! changes:
66//! ```text
67//! your_user        hard nofile 10000
68//! your_user        sort nofile 10000
69//! ```
70//!
71//! Run ``su your_user`` to apply changes to your current shell without reboot.
72//!
73//! [More information](https://duckduckgo.com/?q=Increase+per-process+open+file+limit+linux)
74//!
75//! ## Docker
76//!
77//! Docker uses limit of `65535` by default. To increase it add a parameter:
78//! ```shell
79//! docker run --ulimit nofile=10000:10000 ...
80//! ```
81//!
82//! ## MacOS
83//!
84//! On MacOS raising ulimit doesn't require permissions:
85//! ```console
86//! $ ulimit -n 10000
87//! $ ./your_app
88//! ```
89//!
90//! [More information](https://duckduckgo.com/?q=Increase+per-process+open+file+limit+macos)
91//!
92//! # Too Many Open Files in System <a name='ENFILE'></a>
93//!
94//! | Posix Name | ENFILE |
95//! |---|---|
96//! | Message | `Too many open files in system (os error 23)` |
97//! | Hint | `Increase system open file limit` |
98//! | Link | `https://bit.ly/async-err#ENFILE` |
99//!
100//! ## Common Causes
101//!
102//! 1. Per-process file descriptor limit is larger than system one
103//! 2. File descriptor limit on the system is too small
104//! 3. Limit of number of simultaneous connections is either too high or
105//!    unimplemented
106//!
107//! The (3) can be fixed by applying [`backpressure`] abstraction from this
108//! crate.
109//!
110//! Changing (1) is described in the [section above](#EMFILE).
111//!
112//! The rest of this section discusses how to change system file decriptor
113//! limit.
114//!
115//! ## Choosing a Limit
116//!
117//! Usually system limit depends on the memory and doesn't have to be
118//! increased. So be careful and consult your system docs for more info.
119//!
120//! ## Linux
121//!
122//! Checking the limit:
123//! ```console
124//! $ cat /proc/sys/fs/file-max
125//! 818354
126//! ```
127//!
128//! Setting a limit:
129//! ```console
130//! $ sudo sysctl fs.file-max=1500000
131//! ```
132//!
133//! This only works **until reboot**. On some systems, to preserve this
134//! setting after reboot you can run:
135//! ```console
136//! $ sudo sysctl -w fs.file-max=1500000
137//! ```
138//! (Note `-w`)
139//!
140//! [More information](https://duckduckgo.com/?q=Increase+system+open+file+limit+linux)
141//!
142//! ## MacOS
143//!
144//! Checking a limit:
145//! ```shell
146//! launchctl limit maxfiles
147//! ```
148//!
149//! Setting a limit, **until reboot**:
150//! ```shell
151//! sudo sysctl -w kern.maxfiles=20480
152//! ```
153//!
154//! To make the permanent change, add the following to `/etc/sysctl.conf`:
155//! ```config
156//! kern.maxfiles=65536
157//! kern.maxfilesperproc=65536
158//! ```
159//!
160//! [More information](https://duckduckgo.com/?q=Increase+system+open+file+limit+macos)