view release on metacpan or  search on metacpan

lib/Object/Remote.pm  view on Meta::CPAN

is not set the path is 'perl'

=item OBJECT_REMOTE_LOG_LEVEL

Setting this environment variable will enable logging and send all log messages
at the specfied level or higher to STDERR. Valid level names are: trace debug
verbose info warn error fatal

=item OBJECT_REMOTE_LOG_FORMAT

The format of the logging output is configurable. By setting this environment variable
the format can be controlled via printf style position variables. See
L<Object::Remote::Logging::Logger>.

=item OBJECT_REMOTE_LOG_FORWARDING

Forward log events from remote connections to the local Perl interpreter. Set to 1 to enable
this feature which is disabled by default. See L<Object::Remote::Logging>.

=item OBJECT_REMOTE_LOG_SELECTIONS

Space seperated list of class names to display logs for if logging output is enabled. Default
value is "Object::Remote::Logging" which selects all logs generated by Object::Remote.
See L<Object::Remote::Logging>.

=back

=head1 KNOWN ISSUES

=over 4

=item Large data structures

Object::Remote communication is encapsalated with JSON and values passed to remote objects
will be serialized with it. When sending large data structures or data structures with a lot
of deep complexity (hashes in arrays in hashes in arrays) the processor time and memory requirements
for serialization and deserialization can be either painful or unworkable. During times of
serialization the local or remote nodes will be blocked potentially causing all remote
interpreters to block as well under worse case conditions.

To help deal with this issue it is possible to configure resource ulimits for a Perl interpreter
that is executed by Object::Remote. See C<Object::Remote::Role::Connector::PerlInterpreter>
for details on the perl_command attribute.

=item User can starve run loop of execution opportunities

The Object::Remote run loop is responsible for performing I/O and managing timers in a cooperative
multitasing way but it can only do these tasks when the user has given control to Object::Remote.
There are times when Object::Remote must wait for the user to return control to the run loop and
during these times no I/O can be performed and no timers can be executed.

As an end user of Object::Remote if you depend on connection timeouts, the watch dog or timely
results from remote objects then be sure to hand control back to Object::Remote as soon as you
can.

=item Run loop favors certain filehandles/connections

=item High levels of load can starve timers of execution opportunities

These are issues that only become a problem at large scales. The end result of these two
issues is quite similiar: some remote objects may block while the local run loop is either busy
servicing a different connection or is not executing because control has not yet been returned to
it. For the same reasons timers may not get an opportunity to execute in a timely way.

Internally Object::Remote uses timers managed by the run loop for control tasks. Under
high load the timers can be preempted by servicing I/O on the filehandles and execution
can be severely delayed. This can lead to connection watchdogs not being updated or connection
timeouts taking longer than configured.

=item Deadlocks

Deadlocks can happen quite easily because of flaws in programs that use Object::Remote or
Object::Remote itself so the C<Object::Remote::WatchDog> is available. When used the run
loop will periodically update the watch dog object on the remote Perl interpreter. If the
watch dog goes longer than the configured interval with out being updated then it will
terminate the Perl process. The watch dog will terminate the process even if a deadlock
condition has occured.

=item Log forwarding at scale can starve timers of execution opportunities

Currently log forwarding can be problematic at large scales. When there is a large
amount of log events the load produced by log forwarding can be high enough that it starves
the timers and the remote object watch dogs (if in use) don't get updated in timely way
causing them to erroneously terminate the Perl process. If the watch dog is not in use
then connection timeouts can be delayed but will execute when load settles down enough.

Because of the load related issues Object::Remote disables log forwarding by default.
See C<Object::Remote::Logging> for information on log forwarding.

=back

=head1 SUPPORT

IRC: #web-simple on irc.perl.org

=head1 AUTHOR

mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>

=head1 CONTRIBUTORS

bfwg - Colin Newell (cpan:NEWELLC) <colin.newell@gmail.com>

phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>

triddle - Tyler Riddle (cpan:TRIDDLE) <t.riddle@shadowcat.co.uk>

=head1 SPONSORS

Parts of this code were paid for by

  Socialflow L<http://www.socialflow.com>

  Shadowcat Systems L<http://www.shadow.cat>

=head1 COPYRIGHT

Copyright (c) 2012 the Object::Remote L</AUTHOR>, L</CONTRIBUTORS> and
L</SPONSORS> as listed above.

=head1 LICENSE