view release on metacpan or  search on metacpan

lib/Async/Selector.pm  view on Meta::CPAN

=head2 $selector->register($name => $provider->($condition_input), ...);

Registers resources with the object.
A resource is described as a pair of resource name and resource provider.
You can register as many resources as you like.

The resource name (C<$name>) is an arbitrary string.
It is used to select the resource in C<watch()> method.
If C<$name> is already registered with C<$selector>,
the resource provider is updated with C<$provider> and the old one is discarded.

The resource provider (C<$provider>) is a subroutine reference.
Its return value is supposed to be a scalar data of the resource if it's available,
or C<undef> if it's NOT available.

C<$provider> subroutine takes a scalar argument (C<$condition_input>),
which is given by the user in arguments of C<watch()> method.
C<$provider> can decide whether to provide the resource according to C<$condition_input>.

C<register()> method returns C<$selector> object itself.

lib/Async/Selector/Example/Mojo.pod  view on Meta::CPAN

=item 4.

Access C<http://localhost:3000/> from Web browsers.

=item 5.

You will see two random sequences of characters displayed in textareas,
both of which represent the same resource.

One of the two sequences is updated periodically using Comet (long-polling),
while the other using WebSocket.

=back


=head1 DESCRIPTION

The code above consists of three parts, the resource part, the HTTP
part and the HTML/Javascript part.


=head2 Resource Part

The resource part sets up the resource (C<$resource>) and its
L<Async::Selector> object (C<$selector>).  In this example,
C<$resource> is a random sequence of printable characters, and its
size is 1024 bytes.

C<$resource> is associated with a sequence number (C<$sequence>).
C<$sequence> is incremented when C<$resource> is updated.

C<$resource> is then registered with C<$selector> by C<register()>
method.  In the resource provider subroutine, C<$given_sequence> is
given as the condition input. C<$given_sequence> represents the
sequence number the client currently has. If C<$sequence> is greater
than C<$given_sequence>, it means that the client needs to be updated.
In this case the resource provider exports C<$resource> and
C<$sequence> in a hash reference.

Finally, we use L<Mojo::IOLoop> to periodically update C<$resource>.
When C<$resource> is updated, C<trigger()> method is called on
C<$selector> to notify the clients of the update.


=head2 HTTP Part

In the HTTP part, the events from C<$selector> are exported to Web
browsers via Comet (long-polling) and WebSocket. You might have
to check out L<Mojolicious::Lite> documentation if you are not
familiar with it.

lib/Async/Selector/Example/Mojo.pod  view on Meta::CPAN

C</comet> with C<seq> query parameter being set from C<my_sequence>
variable. C<my_sequence> variable is maintained by the Javascript
program and it is the current sequence number of the resource.

When we get a successful response for the Ajax request, we extract the
sequence number and the resource from the response, show them in the
HTML page, update C<my_sequence> and repeat the request recursively.

Updating C<my_sequence> is very important for Comet connections. If
you do not update it, the server thinks the client is out of date and
needs to be updated. As a result, the server responds to every request
immediately. This is not Comet (long-polling) but just regular
polling. By setting C<my_sequence> appropriately, the client can get a
response ONLY WHEN it needs to be updated. This is possible because
L<Async::Selector> is level-triggered.

C<my_sequence> is initialized to 0. Because the C<$sequence> on the
server side is always greater than 0, the first request for C</comet>
always gets an immediate response from the server.  That way, the
resource is rendered immediately after the HTML page is loaded.  We do
not have to wait for the first update of the resource.

In C<connectWebSocket()> function, we initiate a WebSocket connection
to C</websocket> request path. When we get a message via the
WebSocket, we execute the same decode-and-show routine as in
C<sendCometRequest()>.

Unlike Comet, we do not have to maintain C<my_sequence> for the
WebSocket connection. This is because the WebSocket connection is
persistent.  We can get the resource when it is updated through the
persistent connection.



=head1 AUTHOR

Toshio Ito, C<< <toshioito at cpan.org> >>