Event::RPC(3pm)

💖 Event::RPC 💖

okay so bestie, gather round 🫶 this is Event::RPC, straight outta the User Contributed Perl Documentation section of the manual (yes, Event::RPC(3pm) era, we're fancy). It's an Event based transparent Client/Server RPC framework and honestly? it ate. 💅

---

✨ SYNOPSIS ✨

#-- Server Code
use Event::RPC::Server;
use My::TestModule;
my $server = Event::RPC::Server->new (
    port    => 5555,
    classes => { "My::TestModule" => { ... } },
);
$server->start;

----------------------------------------------------------

#-- Client Code
use Event::RPC::Client;
my $client = Event::RPC::Client->new (
    server   => "localhost",
    port     => 5555,
);
$client->connect;

#-- Call methods of My::TestModule on the server
my $obj = My::TestModule->new ( foo => "bar" );
my $foo = $obj->get_foo;

---

🌸 ABSTRACT 🌸

So Event::RPC is here to help you build Event based networking client/server applications where the client can just... reach over and touch objects/methods on the server like it's no big deal. Totally transparent, no cap. ✨

Network communication is optionally encrypted with IO::Socket::SSL if you're feeling private. 🔒

And the event loop situation? Multiple managers are supported because the API is extensible. Right now what's implemented is Event, Glib and AnyEvent — and that last one literally lets you use nearly every event loop implementation out there for Perl. 🦋

The tea here: AnyEvent was invented after Event::RPC already existed, so Event::RPC started using its own abstraction model. It's giving "I was doing this before it was cool." 😌

---

💅 DESCRIPTION 💅

Event::RPC is two libraries living their best lives: a server and a client.

The server puts out a list of classes and methods that are allowed to be called over the network. More specifically — and this is the iconic part — it acts as a proxy for objects created on the server side (created on demand, whenever a connected client asks), and that proxy handles the client-side method calls, including shipping method arguments over and bringing return values back. 💌

The object proxy handles refcounting and destruction of the objects clients create, properly, like a responsible queen. 👑 Objects as method parameters and as return values are handled too — although there are some limitations, so scroll down for those.

For the client? Whole thing is totally transparent. Once you're connected to the server, it genuinely does not know whether it's calling methods on local or remote objects. Main character energy, but make it RPC. 🌈

And same backwards: the methods on the server never know whether they got called locally or from a connected client. Your application logic is not affected by Event::RPC at all — at least if it has a rudimentary clean OO design. (Have a clean OO design, bestie. Do it for me. 🙏)

For the details on implementing servers and clients, go check the man pages of Event::RPC::Server and Event::RPC::Client.

---

🎀 REQUIREMENTS 🎀

Event::RPC needs either one of these modules on the server (they are not necessary on the client):

Event
Glib
AnyEvent

They're needed for event handling / mainloop implementation. 🌀

If you wanna do SSL encryption you also need to install:

IO::Socket::SSL

And Event::RPC needs minimum one of these for data serialisation:

Sereal (::Decoder and ::Encoder)
CBOR::XS
JSON::XS
Storable

Server and client negotiate automatically which serialiser to use, so you get maximum compatibility. Slay. 🤝

Some words about the Storable module: it's known to be insecure, so Event::RPC uses it as the last option. You can even prevent Event::RPC from using it at all — even when it's installed, which btw is the case for nearly every Perl installation — just check the manpages of Event::Server and Event::Client about the details.

⚠️ And in case you do use Storable: take care that both client and server use exactly the same version of the Storable module! Otherwise Event::RPC client/server communication will fail badly. Like, badly badly. 😭

---

🦋 INSTALLATION 🦋

Latest installation tarballs and online documentation live here:

http://www.exit1.org/Event-RPC/

If your system meets the requirements mentioned above, installation is just:

perl Makefile.PL
make test
make install

Wanna test a specific Event loop implementation? Export the variable EVENT_RPC_LOOP:

export EVENT_RPC_LOOP=Event::RPC::Loop::Glib
make test

Otherwise Event::RPC will fallback to the most appropriate module installed on your system. It'll figure it out, she's smart. 💁‍♀️

---

🌈 EXAMPLES 🌈

The tarball includes an examples/ directory which contains two programs:

server.pl
client.pl

Just execute them with --help to get the usage. They do some very simple communication, but they're genuinely good for testing your setup — especially in a mixed environment. 🍓

---

💀 LIMITATIONS 💀

Okay so even though the classes and objects on the server are accessed transparently by the client, there are some limitations you should be aware of. With a clean object oriented design these should be no problem at all in real applications:

🙈 Direct object data manipulation is forbidden

All objects reside on the server and they stay there! The client just has specially wrapped proxy objects, which trigger the necessary magic to access the object's methods on the server. Complete objects are never transferred from the server to the client, so something like this does not work:

$object->{data} = "changed data";

(assuming $object is a hash ref on the server).

Only method calls are transferred to the server, so even for "simple" data manipulation a method call is necessary:

$object->set_data ("changed data");

Same deal for reading an object attribute. Accessing a hash key will fail:

my $data = $object->{data};

Instead, call a method which returns the 'data' member:

my $data = $object->get_data;

🧚 Methods may exchange objects, but not in a too complex structure

Event::RPC handles methods which return objects. The only requirement is that they are declared as an Object returner on the server (refer to Event::RPC::Server for details) — but it does not work if the object is hidden inside a deep, complex data structure.

An array or hash ref of objects is Ok, but not more. Anything fancier would require too much expensive runtime data inspection. 💸

Object receiving parameters are more restrictive, since even hiding them inside one array or hash ref is not allowed. They must be passed as a direkt argument of the method subroutine.

---

👑 AUTHORS 👑

Jörn Reder <joern AT zyn.de>

---

💜 COPYRIGHT AND LICENSE 💜

Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

k bye bestie, that's the whole page 🫶 this one shipped as perl v5.40.1, dated 2025-09-29, and it's the Event::RPC(3pm) from the User Contributed Perl Documentation. Go build something iconic with it. 💖✨🎀