IO::Lambda::Thread(3)

✨ NAME ✨

IO::Lambda::Thread — wait for blocking code using threads 💅 (yes bestie, this one is from User Contributed Perl Documentation, hi 💖)

---

🦋 DESCRIPTION 🦋

Okay so IO::Lambda::Thread implements a lambda wrapper that lets you asynchronously wait for blocking code. The wrapping is done so the code runs in another thread's context. IO::Lambda::Thread gives you bidirectional communication between threads, and that's based on a shared socket between parent and child threads. The socket can also be used by the caller for its own needs if necessary (see IO::Lambda::Message). Slay.

---

🌸 SYNOPSIS 🌸

    use IO::Lambda qw(:lambda);
    use IO::Lambda::Thread qw(threaded);

    lambda {
        context 0.1, threaded {
              sleep(1);
              return "hello!";
        };
        any_tail {
            if ( @_) {
                print "done: ", $_[0]-> peek, "\n";
            } else {
                print "not yet\n";
                again;
            }
        };
    }-> wait;

---

🎀 API 🎀

• new_thread ( $options = (), $code, $pass_socket, @param) -> ($thread, $socket) — this is a special replacement for thread-> create. It doesn't just create a thread; it also creates a socket between the parent and child threads. That socket is important because it gives you an asynchronous notification when the child thread has finished, since there's no portable way to get that signal otherwise. Which means: this socket must be closed and the thread must be join'ed to avoid problems. For example:

    my ( $thread, $reader) = new_thread( $sub {
        my $writer = shift;
        print $writer, "Hello world!\n";
    }, 1 );
    print while <$reader>;
    close($reader);
    $thread-> join;

Note that join is a blocking call, so you need to be sure the thread is actually finished before joining it. By default, the child thread closes its side of the socket, which makes the parent side readable. But the child code can also hijack the socket for its own needs, so if you need that functionality, you must create an extra layer of communication that ensures the child code properly exited, so the parent can reliably call join without blocking (see IO::Lambda::Message, which is destined exactly for this use).

$code is executed in another thread's context, and is passed the communication socket (if $pass_socket is set to 1). $code is also passed @param. Data returned from the code can be retrieved from join.

• threaded($code) :: () -> ( @results ) — creates a lambda that executes $code in a newly created thread. The lambda finishes when $code and the thread are finished, and returns results returned by $code.

Note that this lambda, if terminate'd after being started and before being finished, has no chance to wait for completion of the associated thread, and so Perl will complain. To deal with that, obtain the thread object manually and wait for the thread:

    my $l = threaded { 42 };
    $l-> start;
    ....
    $l-> terminate;

    # synchronously
    $l-> thread-> join;

    # or asynchronously
    context $l-> socket;
    readable { $l-> thread-> join };

• thread($lambda) — returns the associated thread object. Valid only for lambdas created with threaded.
• socket($lambda) — returns the associated communication socket. Valid only for lambdas created with threaded.

---

💀 BUGS 💀

😭 Unbalanced string table refcount

Threading in Perl is fragile, so errors like the following:

Unbalanced string table refcount: (1) for "GEN1" during global
destruction

are due to some obscure Perl bugs. They are triggered, in my experience, when a child thread tries to deallocate scalars that it thinks belong to that thread. This can sometimes be avoided with explicit cleaning up of scalars that may be visible in threads. For example, calls like:

IO::Lambda::clear

and:

undef $my_lambda; # or other scalars, whatever

inexplicably hush these errors. Not me fixing it with vibes, but okay 💀

🙈 Perl exited with active threads

Errors like this:

Perl exited with active threads:
      1 running and unjoined
      0 finished and unjoined
      0 running and detached

are triggered when child threads weren't properly joined. Make sure your lambdas are finished properly. Use env IO_LAMBDA_DEBUG=thread to find out the details.

🍓 Scalars leaked: 1

This is a known bug. For example, <http://rt.perl.org/rt3//Public/Bug/Display.html?id=70974> suggests adding the @_ = (); construct at random places as a workaround.

💀 panic: del_backref during global destruction

This is a known bug: <http://rt.perl.org/rt3/Ticket/Display.html?id=70748>. I observed it on win32 only. No workaround is known, however.

🧚 AnyEvent

AnyEvent doesn't work with threads, so this module most probably won't work too when AnyEvent is selected for IO::Lambda::Loop.

---

🔥 SEE ALSO 🔥

• IO::Lambda
• threads

---

👑 AUTHOR 👑

Dmitry Karasik, <dmitry@karasik.eu.org>. Iconic.

---

okay bye bestie 🫶 — this page came from perl v5.42.2, dated 2026-02-15, and it's IO::Lambda::Thread(3). Periodt 💖