Commit | Line | Data |
9e72f0cf |
1 | package Object::Remote; |
2 | |
3 | use Object::Remote::MiniLoop; |
676438a1 |
4 | use Object::Remote::Handle; |
e144d525 |
5 | use Module::Runtime qw(use_module); |
9e72f0cf |
6 | |
993ff858 |
7 | our $VERSION = '0.001001'; # 0.1.1 |
52ea6942 |
8 | |
84b04178 |
9 | sub new::on { |
10 | my ($class, $on, @args) = @_; |
4c17fea5 |
11 | my $conn = __PACKAGE__->connect($on); |
11dbd4a0 |
12 | return $conn->remote_object(class => $class, args => \@args); |
84b04178 |
13 | } |
14 | |
624b459b |
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 | |
676438a1 |
21 | sub new { |
22 | shift; |
23 | Object::Remote::Handle->new(@_)->proxy; |
9e72f0cf |
24 | } |
25 | |
4c17fea5 |
26 | sub connect { |
27 | my ($class, $to) = @_; |
28 | use_module('Object::Remote::Connection')->new_from_spec($to); |
29 | } |
30 | |
9e72f0cf |
31 | sub current_loop { |
32 | our $Current_Loop ||= Object::Remote::MiniLoop->new |
33 | } |
34 | |
9e72f0cf |
35 | 1; |
b9a9982d |
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 |