1Event::RPC(3) User Contributed Perl Documentation Event::RPC(3)
2
6 Event::RPC - Event based transparent Client/Server RPC framework
7
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 ----------------------------------------------------------
19 #-- 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 #-- Call methods of My::TestModule on the server
29 my $obj = My::TestModule->new ( foo => "bar" );
30 my $foo = $obj->get_foo;
31
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
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 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 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 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 For details on implementing servers and clients please refer to the man
64 pages of Event::RPC::Server and Event::RPC::Client.
65
67 Event::RPC needs either one of the following modules on the server
68 (they're not necessary on the client):
69 Event
71 Glib
72 AnyEvent
73 They're needed for event handling resp. mainloop implementation. If
75 you like to use SSL encryption you need to install
76 IO::Socket::SSL
78 Event::RPC needs minimum one of the following modules for data
80 serialisation:
81 Sereal (::Decoder and ::Encoder)
83 CBOR::XS
84 JSON::XS
85 Storable
86 Server and client negotiate automatically which serialiser to use to
88 achieve maximum compatibility.
89 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 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
101 You get the latest installation tarballs and online documentation at
102 this location:
103 http://www.exit1.org/Event-RPC/
105 If your system meets the requirements mentioned above, installation is
107 just:
108 perl Makefile.PL
110 make test
111 make install
112 To test a specific Event loop implementation, export the variable
114 EVENT_RPC_LOOP:
115 export EVENT_RPC_LOOP=Event::RPC::Loop::Glib
117 make test
118 Otherwise Event::RPC will fallback to the most appropriate module
120 installed on your system.
121
123 The tarball includes an examples/ directory which contains two
124 programs:
125 server.pl
127 client.pl
128 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
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 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 $object->{data} = "changed data";
147 (assuming $object is a hash ref on the server).
149 Only method calls are transferred to the server, so even for "simple"
151 data manipulation a method call is necessary:
152 $object->set_data ("changed data");
154 As well for reading an object attribute. Accessing a hash key will
156 fail:
157 my $data = $object->{data};
159 Instead call a method which returns the 'data' member:
161 my $data = $object->get_data;
163 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 An array or hash ref of objects is Ok, but not more. This would require
171 to much expensive runtime data inspection.
172 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
178 Jörn Reder <joern AT zyn.de>
179
181 Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.
182 This library is free software; you can redistribute it and/or modify it
184 under the same terms as Perl itself.
185perl v5.36.0 2023-01-20 Event::RPC(3)