/ 
Punk-0.01
/ Punk::WebSocket::Room

NAME

Punk::WebSocket::Room - pub/sub groups of WebSocket connections

SYNOPSIS

use Punk::WebSocket::Room;

sub join_chat {
    my ($c, $ws) = @_;
    my $room = Punk::WebSocket::Room->named('lobby');

    $ws->on(open    => sub { $room->join($_[0]) });
    $ws->on(message => sub {
        my ($ws, $text) = @_;
        $room->broadcast($text, $ws);      # everyone except the sender
    });
    $ws->on(close   => sub { $room->leave($_[0]) });
}

DESCRIPTION

A named group of connections, with one encode per broadcast: the frame is built once and the same bytes are queued to every member.

Membership is held weakly and pruned on every access, so a connection that goes away leaves its rooms by itself - calling "leave" from a close handler is tidy but not required.

A room is per worker. Under a multi-worker server each worker has its own lobby holding only the connections it accepted, and a broadcast reaches those. Fanning out across workers needs a message bus (Redis, a socket to a hub) which this deliberately does not pretend to be.

METHODS

named($name)

The worker's room of that name, created on first use.

join($ws) / leave($ws) / has($ws)

clients

The live members.

count

How many.

broadcast($text, $except?)

broadcast_binary($bytes, $except?)

Send to every open member, optionally skipping one connection (usually the sender). Returns the number sent.

close_all($code = 1000, $reason = '')

Close every member and empty the room.

clear

Empty the room without closing anything.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)