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