AxKit2
view release on metacpan or search on metacpan
lib/AxKit2/Plugin.pm view on Meta::CPAN
Example:
sub hook_logging {
If your plugin needs to hook into the same hook more than once, you will need
to write a C<register()> method as shown above. This is usually the case if you
need continuations for some reason (such as doing asynchronous I/O).
All hooks are called as a method on an instance of the plugin object. Params
below are listed without the C<$plugin> or C<$self> object as the first param.
For some plugins returning C<CONTINUATION> is valid. For details on how
continuations work in AxKit2 see L</CONTINUATIONS> below.
In all cases below, returning C<DECLINED> means other plugins/methods for the
same hook get called. Any other return value means execution stops for that
hook.
Following are the available hooks:
=head2 logging
Params: LEVEL, ARGS
Called when something calls C<< $obj->log(...) >> within AxKit. Logger is
expected to provide a way to set log level and ignore logging below the current
level.
Return Values:
=over 4
=item * C<DECLINED> - continue on to further logging plugins
=item * Anything else - stop logging
=back
=head2 connect
Params: None
Called immediately upon connect.
Return Values:
=over 4
=item * C<OK/DECLINED> - connection is OK to go on to be processed
=item * Anything else - connection is rejected
=back
=head2 pre_request
Params: None
Called before headers are received. Useful if keep-alives are present as this
is called after a keep-alive request finishes but before the next request.
=head2 post_read_request
Params: HEADER
Called after the headers are received and parsed. Passed the C<AxKit2::HTTPHeaders>
object for the incoming headers.
Return Values:
=over 4
=item * C<OK/DECLINED> - Continue processing request if method is either
C<GET> or C<HEAD>.
=item * C<DONE> - assumes response has been sent in full. Stops processing
request.
=item * Anything else - sends the appropriate error response to the browser.
=back
=head2 body_data
Params: BREF
Called for C<POST>, C<PUT>, etc verbs as each packet of body data is received.
The param is a SCALAR reference to the data received.
Return Values:
=over 4
=item * C<OK/DECLINED> - Data received and processed.
=item * C<DONE> - End of data received - process the rest of the request.
=item * Anything else - sends the appropriate error response to the browser.
=back
=head2 uri_translation
Params: HEADERS, URI
Called to translate the URI into a filename and path_info. See
F<plugins/uri_to_file> for an example of what needs to be done.
Return Values:
=over 4
=item * C<OK/DECLINED> - Continue processing the request
=item * C<DONE> - Stop processing. Response has been sent.
=item * Anything Else - send the appropriate error response to the browser.
lib/AxKit2/Plugin.pm view on Meta::CPAN
Params: HEADERS
Return Values - see L</uri_translation> above.
=head2 xmlresponse
Params: PROCESSOR, HEADERS
If this URI is to be treated as an XML request, this hook is for you. Passed an
C<AxKit2::Processor> object and the headers.
Return Value:
=over 4
=item * C<DECLINED> - Not treated as XML. Proceed to regular response hook.
=item * C<OK> [, C<PROCESSOR>]
XML Processed. If provided with a C<PROCESSOR> runs
C<< PROCESSOR->output() >> which in the normal case causes the HTML or
XML to be output to the browser. Stops processing the request at this point.
=item * C<DONE> - Output has been sent to the browser. Stop processing.
=item * Anything Else - send the appropriate error response to the browser.
=back
=head2 response
Params: HEADERS
Main response phase. Used for sending normal responses to the client.
Return Value:
=over 4
=item * C<DECLINED> - Sends a 404 response to the browser.
=item * C<OK> or C<DONE> - Stops processing this request. Response has been
sent.
=item * Anything Else - send the appropriate error response to the browser.
=back
=head2 response_sent
Params: CODE
Called after the response has been sent to the browser. The parameter is the
response code used (e.g. 200 for OK, 404 for Not Found, etc).
The return codes for this hook are used to determine if the connection should
be kept open in a keep-alive request.
Return Value:
=over 4
=item * C<DECLINED/OK> - Use default keep-alive response depending on request
type.
=item * C<DONE> - Request was OK, but don't keep the connection open.
=item * Anything Else - ... TBD.
=back
=head2 disconnect
TBD
=head2 error
Params: ERROR
Called whenever a hook C<die()>s or returns C<SERVER_ERROR>.
Return Value:
=over 4
=item * C<DECLINED> - Use default error handler
=item * C<OK/DONE> - Error was sent to browser. Ignore.
=item * Anything Else - Send a different error to the browser.
=back
=head1 CONTINUATIONS
AxKit2 is entirely single threaded, and so it is important not to do things that
take significant runtime away from the main event loop. A simple example of this
might be looking up a request on a remote web server - while the AxKit process
waits for the response it is important to allow AxKit to continue on processing
other requests.
In order to achieve this AxKit2 uses a simplified version of a technique known
in computer science terms as a I<continuation>.
In simple english, this is a way to suspend execution of one request and
I<continue> it at an arbitrary later time.
AxKit2 has a form of continuations based on the core event loop. Some hooks can
suspend execution by returning C<CONTINUATION>, and have execution of the
request continue when some event has occured.
A typical usage of this is when you need to perform an action that may take some
time. An example of this is disk I/O - typical I/O in the common POSIX
read/write style APIs occurs in a blocking manner - when you ask for a C<read()>
the disk seeks to the position you need it to go to when it can do so and the
read is performed as soon as possible before the API call returns. This may take
very little CPU time because the OS has to wait until the disk head is in the
correct position to perform the actions requested. But it does take "clock" time
which can be put to better use responding to other requests.
In asynchronous I/O the action is requested and a callback is provided to
( run in 1.109 second using v1.01-cache-2.11-cpan-df04353d9ac )