1# NAME
2
3Monoceros - PSGI/Plack server with event driven connection manager, preforking workers
4
5# SYNOPSIS
6
7    % plackup -s Monoceros --max-keepalive-reqs=10000 --max-workers=2 -a app.psgi
8
9# DESCRIPTION
10
11Monoceros is PSGI/Plack server supports HTTP/1.1. Monoceros has a event-driven
12connection manager and preforking workers. Monoceros can keep large amount of
13connection at minimal processes.
14
15                                                          +--------+
16                                                      +---+ worker |
17          TCP       +---------+   UNIX DOMAIN SOCKET  |   +--------+
18    --------------- | manager | ----------------------+
19                    +---------+                       |   +--------+
20    <- keepalive ->              <-- passing fds -->  `---+ worker |
21                                                          +--------+
22
23Features of Monoceros
24
25\- a manager process based on [AnyEvent](https://metacpan.org/pod/AnyEvent) keeps over C10K connections
26
27\- uses [IO::FDPass](https://metacpan.org/pod/IO::FDPass) for passing a file descriptor to workers
28
29\- supports HTTP/1.1 and also supports HTTP/1.0 keepalive
30
31And this server inherit [Starlet](https://metacpan.org/pod/Starlet). Monoceros supports following features too.
32
33\- prefork and graceful shutdown using [Parallel::Prefork](https://metacpan.org/pod/Parallel::Prefork)
34
35\- hot deploy using [Server::Starter](https://metacpan.org/pod/Server::Starter)
36
37\- fast HTTP processing using [HTTP::Parser::XS](https://metacpan.org/pod/HTTP::Parser::XS) (optional)
38
39\- accept4(2) using [Linux::Socket::Accept4](https://metacpan.org/pod/Linux::Socket::Accept4) (optional)
40
41Currently, Monoceros does not support spawn-interval and max-keepalive-reqs.
42
43# COMMAND LINE OPTIONS
44
45In addition to the options supported by [plackup](https://metacpan.org/pod/plackup), Monoceros accepts following options(s).
46Note, the default value of several options is different from Starlet.
47
48## --max-workers=#
49
50number of worker processes (default: 5)
51
52## --timeout=#
53
54seconds until timeout (default: 300)
55
56## --keepalive-timeout=#
57
58timeout for persistent connections (default: 10)
59
60## --max-reqs-per-child=#
61
62max. number of requests to be handled before a worker process exits (default: 1000)
63
64## --min-reqs-per-child=#
65
66if set, randomizes the number of requests handled by a single worker process between the value and that supplied by `--max-reqs-per-chlid` (default: none)
67
68## --max-keepalive-connection=#
69
70max, number of connections to keep in the manager process. If you want to increase this value, You should check your system limitations. (default: half number of POSIX::\_SC\_OPEN\_MAX)
71
72## --max-readahead-reqs=#
73
74max. number of requests to continue to read a request in a worker process. Monoceros can read a next request after the response for maximum throughput. (default: 100)
75
76## --min-readahead-reqs=#
77
78if set, randomizes the number of requests to continue to read a request between the value and that supplied by `--max-readahead-reqs` (default: none)
79
80## --disable-keepalive
81
82disable HTTP keepalive feature (default: enabled)
83
84# RECOMMENDED MODULES
85
86For more performance. I recommends you to install these module.
87
88\- [EV](https://metacpan.org/pod/EV)
89
90\- [HTTP::Parser::XS](https://metacpan.org/pod/HTTP::Parser::XS)
91
92# EXPERIMENTAL FEATURES
93
94- accept4
95
96    Linux only. If Linux::Socket::Accept4 is available, Monoceros use it.
97    accept4(2) can do accept(2) and set SOCK\_CLOEXEC|SOCK\_NONBLOCK at once.
98
99- sendfile
100
101    Monoceros send IO::Handle like body with sendfile(2). [Sys::Sendfile](https://metacpan.org/pod/Sys::Sendfile) is required.
102
103# SEE ALSO
104
105[Starlet](https://metacpan.org/pod/Starlet), [Server::Starter](https://metacpan.org/pod/Server::Starter), [AnyEvent](https://metacpan.org/pod/AnyEvent), [IO::FDPass](https://metacpan.org/pod/IO::FDPass)
106
107# LICENSE
108
109Copyright (C) Masahiro Nagano
110
111This library is free software; you can redistribute it and/or modify
112it under the same terms as Perl itself.
113
114# AUTHOR
115
116Masahiro Nagano <kazeburo@gmail.com>
117