1Event::RPC(3)         User Contributed Perl Documentation        Event::RPC(3)
2
3
4

NAME

6       Event::RPC - Event based transparent Client/Server RPC framework
7

SYNOPSIS

9         #-- Server Code
10         use Event::RPC::Server;
11         use My::TestModule;
12         my $server = Event::RPC::Server->new (
13             port    => 5555,
14             classes => { "My::TestModule" => { ... } },
15         );
16         $server->start;
17
18         ----------------------------------------------------------
19
20         #-- Client Code
21         use Event::RPC::Client;
22         my $client = Event::RPC::Client->new (
23             server   => "localhost",
24             port     => 5555,
25         );
26         $client->connect;
27
28         #-- Call methods of My::TestModule on the server
29         my $obj = My::TestModule->new ( foo => "bar" );
30         my $foo = $obj->get_foo;
31

ABSTRACT

33       Event::RPC supports you in developing Event based networking
34       client/server applications with transparent object/method access from
35       the client to the server. Network communication is optionally encrypted
36       using IO::Socket::SSL. Several event loop managers are supported due to
37       an extensible API. Currently Event, Glib and AnyEvent are implemented.
38       The latter lets you use nearly every event loop implementation
39       available for Perl. AnyEvent was invented after Event::RPC was created
40       and thus Event::RPC started using it's own abstraction model.
41

DESCRIPTION

43       Event::RPC consists of a server and a client library. The server
44       exports a list of classes and methods, which are allowed to be called
45       over the network. More specific it acts as a proxy for objects created
46       on the server side (on demand of the connected clients) which handles
47       client side methods calls with transport of method arguments and return
48       values.
49
50       The object proxy handles refcounting and destruction of objects created
51       by clients properly. Objects as method parameters and return values are
52       handled as well (although with some limitations, see below).
53
54       For the client the whole thing is totally transparent - once connected
55       to the server it doesn't know whether it calls methods on local or
56       remote objects.
57
58       Also the methods on the server newer know whether they are called
59       locally or from a connected client. Your application logic is not
60       affected by Event::RPC at all, at least if it has a rudimentary clean
61       OO design.
62
63       For details on implementing servers and clients please refer to the man
64       pages of Event::RPC::Server and Event::RPC::Client.
65

REQUIREMENTS

67       Event::RPC needs either one of the following modules on the server
68       (they're not necessary on the client):
69
70         Event
71         Glib
72         AnyEvent
73
74       They're needed for event handling resp. mainloop implementation.  If
75       you like to use SSL encryption you need to install
76
77         IO::Socket::SSL
78
79       Event::RPC needs minimum one of the following modules for data
80       serialisation:
81
82         Sereal (::Decoder and ::Encoder)
83         CBOR::XS
84         JSON::XS
85         Storable
86
87       Server and client negotiate automatically which serialiser to use to
88       achieve maximum compatibility.
89
90       Some words about the Storable module: it's known to be insecure, so
91       Event::RPC uses it as the last option. You can even prevent Event::RPC
92       from using it at all (even when it's installed, which is the case for
93       nearly every Perl installation) - check manpages of Event::Server and
94       Event::Client about the details.
95
96       In case you use Storable take care that both client and server use
97       exactly the same version of the Storable module!  Otherwise Event::RPC
98       client/server communication will fail badly.
99

INSTALLATION

101       You get the latest installation tarballs and online documentation at
102       this location:
103
104         http://www.exit1.org/Event-RPC/
105
106       If your system meets the requirements mentioned above, installation is
107       just:
108
109         perl Makefile.PL
110         make test
111         make install
112
113       To test a specific Event loop implementation, export the variable
114       EVENT_RPC_LOOP:
115
116         export EVENT_RPC_LOOP=Event::RPC::Loop::Glib
117         make test
118
119       Otherwise Event::RPC will fallback to the most appropriate module
120       installed on your system.
121

EXAMPLES

123       The tarball includes an examples/ directory which contains two
124       programs:
125
126         server.pl
127         client.pl
128
129       Just execute them with --help to get the usage. They do some very
130       simple communication but are good to test your setup, in particular in
131       a mixed environment.
132

LIMITATIONS

134       Although the classes and objects on the server are accessed
135       transparently by the client there are some limitations should be aware
136       of. With a clean object oriented design these should be no problem in
137       real applications:
138
139   Direct object data manipulation is forbidden
140       All objects reside on the server and they keep there! The client just
141       has specially wrapped proxy objects, which trigger the necessary magic
142       to access the object's methods on the server. Complete objects are
143       never transferred from the server to the client, so something like this
144       does not work:
145
146         $object->{data} = "changed data";
147
148       (assuming $object is a hash ref on the server).
149
150       Only method calls are transferred to the server, so even for "simple"
151       data manipulation a method call is necessary:
152
153         $object->set_data ("changed data");
154
155       As well for reading an object attribute. Accessing a hash key will
156       fail:
157
158         my $data = $object->{data};
159
160       Instead call a method which returns the 'data' member:
161
162         my $data = $object->get_data;
163
164   Methods may exchange objects, but not in a too complex structure
165       Event::RPC handles methods which return objects. The only requirement
166       is that they are declared as a Object returner on the server (refer to
167       Event::RPC::Server for details), but not if the object is hidden inside
168       a deep complex data structure.
169
170       An array or hash ref of objects is Ok, but not more. This would require
171       to much expensive runtime data inspection.
172
173       Object receiving parameters are more restrictive, since even hiding
174       them inside one array or hash ref is not allowed.  They must be passed
175       as a direkt argument of the method subroutine.
176

AUTHORS

178         Jörn Reder <joern AT zyn.de>
179
181       Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.
182
183       This library is free software; you can redistribute it and/or modify it
184       under the same terms as Perl itself.
185
186
187
188perl v5.36.0                      2023-01-20                     Event::RPC(3)
Impressum