.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Mojolicious::Guides::FAQ 3pm" .TH Mojolicious::Guides::FAQ 3pm "2014-09-15" "perl v5.20.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Mojolicious::Guides::FAQ \- Frequently Asked Questions .SH "OVERVIEW" .IX Header "OVERVIEW" This document contains answers for the most frequently asked questions about Mojolicious. .SH "QUESTIONS" .IX Header "QUESTIONS" We hope these answers are to your satisfaction. .SS "How does Mojolicious compare to other Perl web frameworks?" .IX Subsection "How does Mojolicious compare to other Perl web frameworks?" The short answer is \*(L"it doesn't\*(R", because we interpret the term \&\*(L"web framework\*(R" much more literally than others. With the emergence of the real-time web and new technologies such as WebSockets, we are facing new challenges that go way beyond what commonly used modules like \s-1LWP\s0 were designed for. Because of this, Mojolicious contains a whole new \s-1HTTP\s0 client/server stack called Mojo, which was heavily inspired by the original LWPng effort and carefully designed with these new requirements in mind. So while some of the higher abstraction layers might look similar to other web frameworks, it is more of a web toolkit and can even be used as the foundation for more advanced web frameworks. .SS "Why doesn't Mojolicious have any dependencies?" .IX Subsection "Why doesn't Mojolicious have any dependencies?" We are optimizing Mojolicious for user-friendliness and development speed, without compromises. While there are no rules in Mojolicious::Guides::Contributing that forbid dependencies, we do currently discourage adding non-optional ones in favor of a faster and more painless installation process. And we do in fact already use several optional \s-1CPAN\s0 modules such as \s-1EV\s0, IO::Socket::IP, IO::Socket::Socks, IO::Socket::SSL and Plack to provide advanced functionality if they are installed. .SS "Why reinvent wheels?" .IX Subsection "Why reinvent wheels?" Because we can make them rounder. Components specifically designed for user-friendliness and development speed are not easy to come by. We are strong believers of the Perl mantra \*(L"There is more than one way to do it\*(R", and our quest is to develop the best possible solutions for these two criteria. .SS "What about backwards compatibility?" .IX Subsection "What about backwards compatibility?" In conformance with Mojolicious::Guides::Contributing, we will always deprecate a feature before removing or changing it in incompatible ways between major releases. New features can however be marked as experimental to explicitly exclude them from these rules. This gives us the necessary freedom to ensure a healthy future for Mojolicious. So, as long as you are not using anything marked experimental, untested or undocumented, you can always count on backwards compatibility, everything else would be considered a bug. .SS "Why not split up Mojolicious into many smaller distributions?" .IX Subsection "Why not split up Mojolicious into many smaller distributions?" Because there are no advantages, it drastically increases maintenance costs and installation times without giving us anything in return. It would only make sense if we wanted to pass ownership of a module to a new maintainer, which we already have done in the past. .SS "Which versions of Perl are supported by Mojolicious?" .IX Subsection "Which versions of Perl are supported by Mojolicious?" First of all, you need to be aware that according to the perlpolicy, only the two most recent stable release series of Perl are supported by the community and receive bug fixes, which are currently 5.20.x and 5.18.x. Mojolicious follows this model and fully supports these two release series. In addition we will also keep the distribution installable up to a certain legacy version that we deem worthy of supporting, but not specifically optimize for it, this is currently 5.10.1. .SS "Do I need to clean my environment before testing Mojolicious?" .IX Subsection "Do I need to clean my environment before testing Mojolicious?" Mojolicious uses many environment variables both internally and externally, notably (but not exclusively) those starting with the prefix \f(CW\*(C`MOJO_*\*(C'\fR. The test suite expects a clean environment; testing with a non-standard environment is unsupported and is unlikely to succeed. Therefore when installing or upgrading Mojolicious and when running its tests, we highly recommend using an environment which does not set these variables. .SS "What is the difference between blocking and non-blocking operations?" .IX Subsection "What is the difference between blocking and non-blocking operations?" A \fIblocking\fR operation is a subroutine that blocks the execution of the calling subroutine until the subroutine is finished. .PP .Vb 2 \& my $result = blocking_subroutine(); \& ... .Ve .PP A \fInon-blocking\fR operation on the other hand lets the calling subroutine continue execution even though the subroutine is not yet finished. Instead of waiting, the calling subroutine passes along a callback to be executed once the subroutine is finished, this is called continuation-passing style. .PP .Vb 5 \& non_blocking_subroutine(sub { \& my $result = shift; \& ... \& }); \& ... .Ve .SS "Will my code magically become non-blocking with Mojolicious?" .IX Subsection "Will my code magically become non-blocking with Mojolicious?" No, it is not possible to magically make Perl code non-blocking. While Mojolicious has been designed from the ground up for non-blocking I/O and event loops, taking advantage of this requires specialized code available through modules like Mojo::IOLoop and Mojo::UserAgent, or third-party event loops. In the documentation we often refer to this as real-time web, for more information see also \*(L"REAL-TIME \s-1WEB\*(R"\s0 in Mojolicious::Guides::Cookbook. .SS "What is an event loop?" .IX Subsection "What is an event loop?" An event loop is basically a loop that continually tests for external events and executes the appropriate callbacks to handle them, it is often the main loop in a program. Non-blocking tests for readability/writability of file descriptors and timers are commonly used events for highly scalable network servers, because they allow a single process to handle thousands of client connections concurrently. .PP .Vb 3 \& while (1) { \& my @readable = test_fds_for_readability(); \& handle_readable_fds(@readable); \& \& my @writable = test_fds_for_writability(); \& handle_writable_fds(@writable); \& \& my @expired = test_timers(); \& handle_timers(@expired); \& } .Ve .PP In Mojolicious this event loop is Mojo::IOLoop. .ie n .SS "What does the error ""Maximum message size exceeded"" mean?" .el .SS "What does the error ``Maximum message size exceeded'' mean?" .IX Subsection "What does the error Maximum message size exceeded mean?" To protect your applications from excessively large requests and responses, our \s-1HTTP\s0 parser has a cap after which it will automatically stop accepting new data, and in most cases force the connection to be closed. This limit is around 10MB by default, you can use the attribute \&\*(L"max_message_size\*(R" in Mojo::Message or \f(CW\*(C`MOJO_MAX_MESSAGE_SIZE\*(C'\fR environment variable to change this value. .ie n .SS "What does the error ""Maximum line size exceeded"" mean?" .el .SS "What does the error ``Maximum line size exceeded'' mean?" .IX Subsection "What does the error Maximum line size exceeded mean?" This is a very similar protection mechanism to the one described in the previous answer, but a little more specific. It limits the maximum length of any \f(CW\*(C`\ex0d\ex0a\*(C'\fR terminated part of a \s-1HTTP\s0 message, such as request line, status line and headers. This limit is around 10KB by default, you can use the attributes \*(L"max_line_size\*(R" in Mojo::Message and \&\*(L"max_line_size\*(R" in Mojo::Headers or \f(CW\*(C`MOJO_MAX_LINE_SIZE\*(C'\fR environment variable to change this value. .ie n .SS "What does the error ""Maximum buffer size exceeded"" mean?" .el .SS "What does the error ``Maximum buffer size exceeded'' mean?" .IX Subsection "What does the error Maximum buffer size exceeded mean?" This protection mechanism is very similar to those mentioned in the two previous answers. It limits how much content the \s-1HTTP\s0 parser is allowed to buffer when parsing chunked, compressed and multipart messages. This limit is around 256KB by default, you can use the attribute \&\*(L"max_buffer_size\*(R" in Mojo::Content or \f(CW\*(C`MOJO_MAX_BUFFER_SIZE\*(C'\fR environment variable to change this value. .ie n .SS "What does the error ""\s-1EV\s0 does not work with ithreads"" mean?" .el .SS "What does the error ``\s-1EV\s0 does not work with ithreads'' mean?" .IX Subsection "What does the error EV does not work with ithreads mean?" The Mojolicious user agent and web servers are based on an event loop that supports multiple reactor backends. One of these backends is \s-1EV\s0, it is very fast and will be automatically used if installed. On Windows however, the \&\f(CW\*(C`ithreads\*(C'\fR based \f(CW\*(C`fork()\*(C'\fR emulation can interfere with it, and you may have to use the \f(CW\*(C`MOJO_REACTOR\*(C'\fR environment variable to enforce a more portable one. .PP .Vb 1 \& MOJO_REACTOR=Mojo::Reactor::Poll .Ve .ie n .SS "What does ""Your secret passphrase needs to be changed"" mean?" .el .SS "What does ``Your secret passphrase needs to be changed'' mean?" .IX Subsection "What does Your secret passphrase needs to be changed mean?" Mojolicious uses secret passphrases for security features such as signed cookies. It defaults to using \*(L"moniker\*(R" in Mojolicious, which is not very secure, so we added this log message as a reminder. You can change the passphrase with the attribute \*(L"secrets\*(R" in Mojolicious. .PP .Vb 1 \& $app\->secrets([\*(AqMy very secret passphrase.\*(Aq]); .Ve .ie n .SS "What does ""Nothing has been rendered, expecting delayed response"" mean?" .el .SS "What does ``Nothing has been rendered, expecting delayed response'' mean?" .IX Subsection "What does Nothing has been rendered, expecting delayed response mean?" Mojolicious has been designed from the ground up for non-blocking I/O and event loops. So when a new request comes in and no response is generated right away, it will assume that this was intentional and return control to the web server, which can then handle other requests while waiting for events such as timers to finally generate a response. .ie n .SS "What does ""Inactivity timeout"" mean?" .el .SS "What does ``Inactivity timeout'' mean?" .IX Subsection "What does Inactivity timeout mean?" To protect your applications from denial-of-service attacks, all connections have an inactivity timeout which limits how long a connection may be inactive before being closed automatically. It defaults to \f(CW20\fR seconds for the user agent and \f(CW15\fR seconds for all built-in web servers, and can be changed with the attributes \*(L"inactivity_timeout\*(R" in Mojo::UserAgent and \&\*(L"inactivity_timeout\*(R" in Mojo::Server::Daemon or the \f(CW\*(C`MOJO_INACTIVITY_TIMEOUT\*(C'\fR environment variable. This timeout always applies, so you might have to tweak it for applications that take a long time to process a request. .ie n .SS "What does ""Premature connection close"" mean?" .el .SS "What does ``Premature connection close'' mean?" .IX Subsection "What does Premature connection close mean?" This error message is often related to the one above, and means that the web server closed the connection before the user agent could receive the whole response or that the user agent got destroyed, which forces all connections to be closed immediately. .ie n .SS "What does ""Worker 31842 has no heartbeat, restarting"" mean?" .el .SS "What does ``Worker 31842 has no heartbeat, restarting'' mean?" .IX Subsection "What does Worker 31842 has no heartbeat, restarting mean?" As long as they are accepting new connections, worker processes of all built-in preforking web servers send heartbeat messages to the manager process at regular intervals, to signal that they are still responsive. A blocking operation such as an infinite loop in your application can prevent this, and will force the affected worker to be restarted after a timeout. This timeout defaults to \f(CW20\fR seconds and can be extended with the attribute \&\*(L"heartbeat_interval\*(R" in Mojo::Server::Prefork if your application requires it. .SH "MORE" .IX Header "MORE" You can continue with Mojolicious::Guides now or take a look at the Mojolicious wiki , which contains a lot more documentation and examples by many different authors. .SH "SUPPORT" .IX Header "SUPPORT" If you have any questions the documentation might not yet answer, don't hesitate to ask on the mailing-list or the official \s-1IRC\s0 channel \f(CW\*(C`#mojo\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR.