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