lib/Object/Remote.pm

   1 package Object::Remote;
   2
   3 use Object::Remote::MiniLoop;
   4 use Object::Remote::Handle;
   5 use Object::Remote::Logging qw( :log );
   6 use Module::Runtime qw(use_module);
   7
   8 our $VERSION = '0.002003'; # 0.2.3
   9
  10 BEGIN {
  11   Object::Remote::Logging->init_logging;
  12 }
  13
  14 sub new::on {
  15   my ($class, $on, @args) = @_;
  16   my $conn = __PACKAGE__->connect($on);
  17   log_trace { sprintf("constructing instance of $class on connection for child pid of %i", $conn->child_pid) };
  18   return $conn->remote_object(class => $class, args => \@args);
  19 }
  20
  21 sub can::on {
  22   my ($class, $on, $name) = @_;
  23   my $conn = __PACKAGE__->connect($on);
  24   log_trace { "Invoking remote \$class->can('$name')" };
  25   return $conn->remote_sub(join('::', $class, $name));
  26 }
  27
  28 sub new {
  29   shift;
  30   Object::Remote::Handle->new(@_)->proxy;
  31 }
  32
  33 sub connect {
  34   my ($class, $to) = @_;
  35   use_module('Object::Remote::Connection')->maybe::start::new_from_spec($to);
  36 }
  37
  38 sub current_loop {
  39   our $Current_Loop ||= Object::Remote::MiniLoop->new
  40 }
  41
  42 1;
  43
  44 =head1 NAME
  45
  46 Object::Remote - Call methods on objects in other processes or on other hosts
  47
  48 =head1 SYNOPSIS
  49
  50 Creating a connection:
  51
  52   use Object::Remote;
  53
  54   my $conn = Object::Remote->connect('myserver'); # invokes ssh
  55
  56 Calling a subroutine:
  57
  58   my $capture = IPC::System::Simple->can::on($conn, 'capture');
  59
  60   warn $capture->('uptime');
  61
  62 Using an object:
  63
  64   my $eval = Eval::WithLexicals->new::on($conn);
  65
  66   $eval->eval(q{my $x = `uptime`});
  67
  68   warn $eval->eval(q{$x});
  69
  70 Importantly: 'myserver' only requires perl 5.8+ - no non-core modules need to
  71 be installed on the far side, Object::Remote takes care of it for you!
  72
  73 =head1 DESCRIPTION
  74
  75 Object::Remote allows you to create an object in another process - usually
  76 one running on another machine you can connect to via ssh, although there
  77 are other connection mechanisms available.
  78
  79 The idea here is that in many cases one wants to be able to run a piece of
  80 code on another machine, or perhaps many other machines - but without having
  81 to install anything on the far side.
  82
  83 =head1 COMPONENTS
  84
  85 =head2 Object::Remote
  86
  87 The "main" API, which provides the L</connect> method to create a connection
  88 to a remote process/host, L</new::on> to create an object on a connection,
  89 and L</can::on> to retrieve a subref over a connection.
  90
  91 =head2 Object::Remote::Connection
  92
  93 The object representing a connection, which provides the
  94 L<Object::Remote::Connection/remote_object> and
  95 L<Object::Remote::Connection/remote_sub> methods that are used by
  96 L</new::on> and L</can::on> to return proxies for objects and subroutines
  97 on the far side.
  98
  99 =head2 Object::Remote::Future
 100
 101 Code for dealing with asynchronous operations, which provides the
 102 L<Object::Remote::Future/start::method> syntax for calling a possibly
 103 asynchronous method without blocking, and
 104 L<Object::Remote::Future/await_future> and L<Object::Remote::Future/await_all>
 105 to block until an asynchronous call completes or fails.
 106
 107 =head1 METHODS
 108
 109 =head2 connect
 110
 111   my $conn = Object::Remote->connect('-'); # fork()ed connection
 112
 113   my $conn = Object::Remote->connect('myserver'); # connection over ssh
 114
 115   my $conn = Object::Remote->connect('user@myserver'); # connection over ssh
 116
 117   my $conn = Object::Remote->connect('root@'); # connection over sudo
 118
 119 =head2 new::on
 120
 121   my $eval = Eval::WithLexicals->new::on($conn);
 122
 123   my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect
 124
 125   my $obj = Some::Class->new::on($conn, %args); # with constructor arguments
 126
 127 =head2 can::on
 128
 129   my $hostname = Sys::Hostname->can::on($conn, 'hostname');
 130
 131   my $hostname = Sys::Hostname->can::on('myserver', 'hostname');
 132
 133 =head1 ENVIRONMENT
 134
 135 =over 4
 136
 137 =item OBJECT_REMOTE_PERL_BIN
 138
 139 When starting a new Perl interpreter the contents of this environment
 140 variable will be used as the path to the executable. If the variable
 141 is not set the path is 'perl'
 142
 143 =item OBJECT_REMOTE_LOG_LEVEL
 144
 145 Setting this environment variable will enable logging and send all log messages
 146 at the specfied level or higher to STDERR. Valid level names are: trace debug
 147 verbose info warn error fatal
 148
 149 =item OBJECT_REMOTE_LOG_FORMAT
 150
 151 The format of the logging output is configurable. By setting this environment variable
 152 the format can be controlled via printf style position variables. See
 153 L<Object::Remote::Logging::Logger>.
 154
 155 =item OBJECT_REMOTE_LOG_FORWARDING
 156
 157 Forward log events from remote connections to the local Perl interpreter. Set to 1 to enable
 158 this feature which is disabled by default. See L<Object::Remote::Logging>.
 159
 160 =item OBJECT_REMOTE_LOG_SELECTIONS
 161
 162 Space seperated list of class names to display logs for if logging output is enabled. Default
 163 value is "Object::Remote::Logging" which selects all logs generated by Object::Remote.
 164 See L<Object::Remote::Logging::Router>.
 165
 166 =back
 167
 168 =head1 SUPPORT
 169
 170 IRC: #web-simple on irc.perl.org
 171
 172 =head1 AUTHOR
 173
 174 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 175
 176 =head1 CONTRIBUTORS
 177
 178 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
 179
 180 triddle - Tyler Riddle (cpan:TRIDDLE) <t.riddle@shadowcat.co.uk>
 181
 182 =head1 SPONSORS
 183
 184 Parts of this code were paid for by
 185
 186   Socialflow L<http://www.socialflow.com>
 187
 188   Shadowcat Systems L<http://www.shadow.cat>
 189
 190 =head1 COPYRIGHT
 191
 192 Copyright (c) 2012 the Object::Remote L</AUTHOR>, L</CONTRIBUTORS> and
 193 L</SPONSORS> as listed above.
 194
 195 =head1 LICENSE
 196
 197 This library is free software and may be distributed under the same terms
 198 as perl itself.
 199
 200 =cut