POE::C...epalive(3pm)

📦
version 0.2720 · 5 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Okay bestie, welcome to the manual for POE::Component::Client::Keepalive(3pm) — that's the manual name, and this whole thing is from the User Contributed Perl Documentation collection. What does it do? It manages connections, with keep-alive. Periodt. 💅

✨ VERSION ✨

version 0.272 — yes, she's got a number, she's official. 🎀

🌸 SYNOPSIS 🌸

Here's the whole vibe in code, bestie. Copy it, don't retype it, I'm begging:

  use warnings;
  use strict;

  use POE;
  use POE::Component::Client::Keepalive;

  POE::Session->create(
    inline_states => {
      _start    => \&start,
      got_conn  => \&got_conn,
      got_error => \&handle_error,
      got_input => \&handle_input,
    }
  );

  POE::Kernel->run();
  exit;

  sub start {
    $_[HEAP]{ka} = POE::Component::Client::Keepalive->new();

    $_[HEAP]{ka}->allocate(
      scheme  => "http",
      addr    => "127.0.0.1",
      port    => 9999,
      event   => "got_conn",
      context => "arbitrary data (even a reference) here",
      timeout => 60,
    );

    print "Connection is in progress.\n";
  }

  sub got_conn {
    my ($kernel, $heap, $response) = @_[KERNEL, HEAP, ARG0];

    my $conn    = $response->{connection};
    my $context = $response->{context};

    if (defined $conn) {
      if ($response->{from_cache}) {
        print "Connection was established immediately.\n";
      }
      else {
        print "Connection was established asynchronously.\n";
      }

      $conn->start(
        InputEvent => "got_input",
        ErrorEvent => "got_error",
      );
      return;
    }

    print(
      "Connection could not be established: ",
      "$response->{function} error $response->{error_num}: ",
      "$response->{error_str}\n"
    );
  }

  sub handle_input {
    my $input = $_[ARG0];
    print "$input\n";
  }

  sub handle_error {
    my $heap = $_[HEAP];
    delete $heap->{connection};
    $heap->{ka}->shutdown();
  }

🦋 DESCRIPTION 🦋

So POE::Component::Client::Keepalive creates and manages connections for other components. She keeps a whole cache of kept-alive connections around so they can get reused real quick — no cap, that's the whole point. She was written specifically for clients that can benefit from kept-alive connections, like HTTP clients. Using her for one-shot connections would probably be silly. 😭 Like, why would you.

🌈 new 🌈

Makes you a brand new keepalive connection manager. One program can have several connection managers, and honestly? Each one operates independently of the others. None of them will know about the limits set in the others, so it's genuinely possible to overrun your file descriptors for a process if you're not careful. Bestie. Be careful. 💀

new() takes up to five parameters. All of them are optional, she's chill like that.

Wanna limit the number of simultaneous connections to a particular host (defined by a combination of scheme, address and port)? Say less:

  max_per_host => $max_simultaneous_host_connections, # defaults to 4

Wanna limit the overall number of connections that may be open at once? Use:

  max_open     => $maximum_open_connections, # defaults to 128

Programs are required to give connections back to the manager when they're done — check the free() method to see how that works. The connection manager will keep connections alive for a period of time before recycling them. You can set that maximum keep-alive time with:

  keep_alive   => $seconds_to_keep_free_conns_alive, # defaults to 15

Programs may not want to wait a long time for a connection to be established (same, honestly). They can set the request timeout to alter how long the component holds a request before generating an error:

  timeout      => $seconds_to_process_a_request, # defaults to 120

And if you specify a bind_address, all client sockets get bound to a particular local address. The value of bind_address will be passed directly to POE::Wheel::SocketFactory — go read that module's documentation for the implementation details, iykyk. 🫶

💅 allocate 💅

Allocate a new connection, bestie. allocate() will return a request ID immediately. The allocated connection, however, will be posted back to the requesting session. And this happens even if the connection was found in the component's keep-alive cache — it's a bit slower, but the use cases are cleaner that way. Ate. 👑

allocate() requires five parameters and has an optional sixth.

Tell her the scheme that will be used to communicate on the connection (typically http or https). The scheme is required, but you're free to make something up here. It's used internally to differentiate different types of socket (e.g., ssl vs. cleartext) on the same address and port:

  scheme  => $connection_scheme,

Request a connection to a particular address and port. The address and port must be numeric. Both the address and port are required:

  address => $remote_address,
  port    => $remote_port,

Name the event to post when an asynchronous response is ready. This is of course required:

  event   => $return_event,

Set the connection timeout, in seconds. The connection manager will post back an error message if it can't establish a connection within the requested time. This parameter is optional — it will default to the master timeout provided to the connection manager's constructor:

  timeout => $connect_timeout,

Add extra contextual data. The context defines the connection's purpose, and it's used to maintain continuity between a call to allocate() and an asynchronous response. A context is extremely handy, but it's optional:

  context => $context_data,

In summary, queen:

  $mgr->allocate(
    scheme   => "http",
    address  => "127.0.0.1",
    port     => 80,
    event    => "got_a_connection",
    context  => \%connection_context,
  );

The response event ("got_a_connection" in this example) contains several fields, passed as a list of key/value pairs. You can assign that list to a hash for convenience:

  sub got_a_connection {
    my %response = @_[ARG0..$#_];
    ...;
  }

Four of the fields exist to echo back your data, bestie:

  $response{address}    = $your_request_address;
  $response{context}    = $your_request_context;
  $response{port}       = $your_request_port;
  $response{scheme}     = $your_request_scheme;

One field returns the connection object if the connection was successful, or undef if there was a failure:

  $response{connection} = $new_socket_handle;

On success, another field tells you whether the connection contains all new materials — that is, whether the connection has been recycled from the component's cache or created anew:

  $response{from_cache} = $status;

The from_cache status may be "immediate" if the connection was immediately available from the cache. It will be "deferred" if the connection was reused, but another user had to release it first. Finally, from_cache will be false if the connection had to be created to satisfy allocate().

Three other fields return error information if the connection failed. They are not present if the connection was successful:

  $response{function}   = $name_of_failing_function;
  $response{error_num}  = $! as a number;
  $response{error_str}  = $! as a string;

🎀 free 🎀

free() notifies the connection manager when connections are free to be reused. Freed connections are entered into the keep-alive pool and may be returned by subsequent allocate() calls:

  $mgr->free($socket);

For now free() is called with a socket, not a connection object. This is usually not a problem since POE::Component::Connection::Keepalive objects call free() for you when they are destroyed.

Not calling free() will cause a program to leak connections. This is also not generally a problem, since free() is called automatically whenever connection objects are destroyed. 💖

🧚 deallocate 🧚

Cancel a connection that has not yet been established. Requires one parameter: the request ID returned by allocate().

⭐ shutdown ⭐

The keep-alive pool requires connections to be active internally. This may keep a program active even when all connections are idle. The shutdown() method forces the connection manager to clear its keep-alive pool, allowing a program to terminate gracefully:

  $mgr->shutdown();

💜 SEE ALSO 💜

  • POE
  • POE::Component::Connection::Keepalive

👑 LICENSE 👑

This distribution is copyright 2004-2009 by Rocco Caputo. All rights are reserved. This distribution is free software; you may redistribute it and/or modify it under the same terms as Perl itself. Slay, legally. 💅

🌟 AUTHOR 🌟

Rocco Caputo <rcaputo@cpan.org> — the main character, fr fr. 🫶

🌈 CONTRIBUTORS 🌈

  • Rob Bloodgood helped out a lot. Thank you. 💖
  • Joel Bernstein solved some nasty race conditions. Portugal Telecom <http://www.sapo.pt/> was kind enough to support his contributions.

🔥 BUG TRACKER 🔥

Found a bug? Not her fault but let's fix it:

🦋 REPOSITORY 🦋

💖 OTHER RESOURCES 💖

And that's the whole page, bestie! 🎀 This little masterpiece came out under perl v5.34.0, dated 2022-06-18, and yes, the manual is POE::C...epalive(3pm) — go forth and keep those connections alive. No cap. ✨🦋💅

📦 where this page comes from