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_debug { 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   return $conn->remote_sub(join('::', $class, $name));
  25 }
  26
  27 sub new {
  28   shift;
  29   Object::Remote::Handle->new(@_)->proxy;
  30 }
  31
  32 sub connect {
  33   my ($class, $to) = @_;
  34   use_module('Object::Remote::Connection')->maybe::start::new_from_spec($to);
  35 }
  36
  37 sub current_loop {
  38   our $Current_Loop ||= Object::Remote::MiniLoop->new
  39 }
  40
  41 1;
  42
  43 =head1 NAME
  44
  45 Object::Remote - Call methods on objects in other processes or on other hosts
  46
  47 =head1 SYNOPSIS
  48
  49 Creating a connection:
  50
  51   use Object::Remote;
  52
  53   my $conn = Object::Remote->connect('myserver'); # invokes ssh
  54
  55 Calling a subroutine:
  56
  57   my $capture = IPC::System::Simple->can::on($conn, 'capture');
  58
  59   warn $capture->('uptime');
  60
  61 Using an object:
  62
  63   my $eval = Eval::WithLexicals->new::on($conn);
  64
  65   $eval->eval(q{my $x = `uptime`});
  66
  67   warn $eval->eval(q{$x});
  68
  69 Importantly: 'myserver' only requires perl 5.8+ - no non-core modules need to
  70 be installed on the far side, Object::Remote takes care of it for you!
  71
  72 =head1 DESCRIPTION
  73
  74 Object::Remote allows you to create an object in another process - usually
  75 one running on another machine you can connect to via ssh, although there
  76 are other connection mechanisms available.
  77
  78 The idea here is that in many cases one wants to be able to run a piece of
  79 code on another machine, or perhaps many other machines - but without having
  80 to install anything on the far side.
  81
  82 =head1 COMPONENTS
  83
  84 =head2 Object::Remote
  85
  86 The "main" API, which provides the L</connect> method to create a connection
  87 to a remote process/host, L</new::on> to create an object on a connection,
  88 and L</can::on> to retrieve a subref over a connection.
  89
  90 =head2 Object::Remote::Connection
  91
  92 The object representing a connection, which provides the
  93 L<Object::Remote::Connection/remote_object> and
  94 L<Object::Remote::Connection/remote_sub> methods that are used by
  95 L</new::on> and L</can::on> to return proxies for objects and subroutines
  96 on the far side.
  97
  98 =head2 Object::Remote::Future
  99
 100 Code for dealing with asynchronous operations, which provides the
 101 L<Object::Remote::Future/start::method> syntax for calling a possibly
 102 asynchronous method without blocking, and
 103 L<Object::Remote::Future/await_future> and L<Object::Remote::Future/await_all>
 104 to block until an asynchronous call completes or fails.
 105
 106 =head1 METHODS
 107
 108 =head2 connect
 109
 110   my $conn = Object::Remote->connect('-'); # fork()ed connection
 111
 112   my $conn = Object::Remote->connect('myserver'); # connection over ssh
 113
 114   my $conn = Object::Remote->connect('user@myserver'); # connection over ssh
 115
 116   my $conn = Object::Remote->connect('root@'); # connection over sudo
 117
 118 =head2 new::on
 119
 120   my $eval = Eval::WithLexicals->new::on($conn);
 121
 122   my $eval = Eval::WithLexicals->new::on('myserver'); # implicit connect
 123
 124   my $obj = Some::Class->new::on($conn, %args); # with constructor arguments
 125
 126 =head2 can::on
 127
 128   my $hostname = Sys::Hostname->can::on($conn, 'hostname');
 129
 130   my $hostname = Sys::Hostname->can::on('myserver', 'hostname');
 131
 132 =head1 SUPPORT
 133
 134 IRC: #web-simple on irc.perl.org
 135
 136 =head1 AUTHOR
 137
 138 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 139
 140 =head1 CONTRIBUTORS
 141
 142 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
 143
 144 =head1 SPONSORS
 145
 146 Parts of this code were paid for by
 147
 148   Socialflow L<http://www.socialflow.com>
 149
 150   Shadowcat Systems L<http://www.shadow.cat>
 151
 152 =head1 COPYRIGHT
 153
 154 Copyright (c) 2012 the Object::Remote L</AUTHOR>, L</CONTRIBUTORS> and
 155 L</SPONSORS> as listed above.
 156
 157 =head1 LICENSE
 158
 159 This library is free software and may be distributed under the same terms
 160 as perl itself.
 161
 162 =cut