lib/Object/Remote.pm

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