POE::Component(3pm)

✨ POE::Component ✨

okay bestie, welcome to the manual page for POE::Component 💖 — and yes, it's from the User Contributed Perl Documentation crew, we love that for them. event driven objects or subsystems, no biggie. 👑

---

🌸 NAME 🌸

POE::Component — event driven objects or subsystems. that's it. that's the whole vibe. 💅

---

🦋 SYNOPSIS 🦋

See specific components. yeah fr, this one's a namespace, not a script, so there's nothing to run here. go look at the actual component you want, bestie. ✨

---

💜 DESCRIPTION 💜

okay so POE "components" are event-driven modules that generally encapsulate mid- to high-level program features. like, mid-to-high-level. not the baby stuff, not the whole entire app either. 🫶

for example, POE::Component::Client::DNS performs message-based asynchronous resolver lookups. and POE::Component::Server::TCP is a basic asynchronous network server. two icons, honestly. 🌈

the POE::Component namespace was started as a place for contributors to publish their POE-based modules without requiring coordination with the main POE distribution. so you didn't have to slide into the core maintainers' DMs, you could just drop your module. iconic behavior. 👑

the namespace predates the -X convention, otherwise you'd be reading about POEx instead. we were this close. 😭

and as with many things in Perl, there is more than one way to implement component interfaces. newer components sport OO interfaces, and some even use Moose, but older ones are solely message driven. respect the elders. 🙈

---

🎀 OBJECT ORIENTED COMPONENTS 🎀

one way to create object-oriented components is to embed a POE::Session instance within an object. the way that works: you create the session during the object's constructor, set the session's alias to something unique, and save a copy of the alias in the object. periodt. 💅

package Asynchrotron;

my $alias_index = 0;

sub new {
  my $class = shift;
  my $self = bless {
    alias => __PACKAGE__ . " " . ++$alias_index;
  }, $class;

  POE::Session->create(
    object_states => [
      $self => {
        _start       => "_poe_start",
        do_something => "_poe_do_something",
      },
    ],
  );
  return $self;
}

sub _poe_start {
  $_[KERNEL]->alias_set($_[OBJECT]->{alias});
}

the alias lets object methods pass events into the session without having to store something about the session. and the POE::Kernel call() transfers execution from the caller session's context into the component's session. so it hops sessions, effortlessly, like a girl switching group chats. 🦋

sub do_something {
  my $self = shift;
  print "Inside the caller's session right now: @_\n";
  $poe_kernel->call($self->{alias}, "do_something", @_);
}

sub _poe_do_something {
  my @args = @_[ARG0..$#_];
  print "Inside the component's session now: @args\n";
  $_[OBJECT]{count}++;
}

both $_[HEAP] and $_[OBJECT] are visible within the component's session. 💖

• $_[HEAP] can be used for ultra-private encapsulation
• $_[OBJECT] may be used for data visible by accessors

sub get_count {
  my $self = shift;
  return $self->{count}; # $_[OBJECT]{count} above
}

⚠️ too many sessions may bog down object creation and destruction, so avoid creating them for every object. this is the one caveat, don't skip it, bestie. 💀

---

🌈 SEE ALSO 🌈

the SEE ALSO section in POE contains a table of contents covering the entire POE distribution. go check it, it's giving directory. 🗺️

POE::Stage is a nascent project to formalize POE components, make POE::Kernel more object-oriented, and provide syntactic and semantic sugar for many common aspects of POE::Component development. it's also easier to type. 💅 please investigate the project. ideas and tuits are badly needed to help get the project off the ground. like genuinely, they need help, this is a call to action, not a drill. 📣

---

📝 TO DO 📝

document the customary (but not mandatory!) process of creating and publishing a component. so like, someone please do that. not me though. 😭

---

👑 AUTHORS & COPYRIGHTS 👑

each component is written and copyrighted separately. every single one, its own little main character. 🎀

please see POE for more information about authors and contributors. 🫶

---

and that's the whole page, bestie!! this gem is from perl v5.34.0, dated 2022-03-25, and it lives at POE::Component(3pm). thanks for reading, mwah 💋💖✨