---
name: "IO::Async::Loop::Epoll"
section: "3pm"
platform: "linux"
package: "libio-async-loop-epoll-perl"
version: "0.23-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/IO::Async::Loop::Epoll"
---

# IO::Async::Loop::Epoll(3pm)

use "IO::Async" with "epoll" on Linux

## NAME

"IO::Async::Loop::Epoll" - use "IO::Async" with "epoll" on Linux

## SYNOPSIS

```
   use IO::Async::Loop::Epoll;
   use IO::Async::Stream;
   use IO::Async::Signal;
   my $loop = IO::Async::Loop::Epoll->new;
   $loop->add( IO::Async::Stream->new(
         read_handle => \*STDIN,
         on_read => sub {
            my ( $self, $buffref ) = @_;
            while( $$buffref =~ s/^(.*)\r?\n// ) {
               print "You said: $1\n";
            }
         },
   ) );
   $loop->add( IO::Async::Signal->new(
         name => 'INT',
         on_receipt => sub {
            print "SIGINT, will now quit\n";
            $loop->stop;
         },
   ) );
   $loop->run;
```

## DESCRIPTION

This subclass of IO::Async::Loop uses `epoll(7)` on Linux to perform read-ready and write-ready tests so that the O(1) high-performance multiplexing of Linux's `epoll_pwait(2)` syscall can be used.

The `"epoll"` Linux subsystem uses a persistent registration system, meaning that better performance can be achieved in programs using a large number of filehandles. Each `epoll_pwait(2)` syscall only has an overhead proportional to the number of ready filehandles, rather than the total number being watched. For more detail, see the `epoll(7)` manpage.

This class uses the `epoll_pwait(2)` system call, which atomically switches the process's signal mask, performs a wait exactly as `epoll_wait(2)` would, then switches it back. This allows a process to block the signals it cares about, but switch in an empty signal mask during the poll, allowing it to  handle file IO and signals concurrently.

## CONSTRUCTOR

### new

```
   $loop = IO::Async::Loop::Epoll->new();
```

This function returns a new instance of a `"IO::Async::Loop::Epoll"` object.

## METHODS

As this is a subclass of IO::Async::Loop, all of its methods are inherited. Expect where noted below, all of the class's methods behave identically to `"IO::Async::Loop"`.

### loop\_once

```
   $count = $loop->loop_once( $timeout );
```

This method calls `epoll_pwait(2)`, and processes the results of that call. It returns the total number of `"IO::Async::Notifier"` callbacks invoked, or `"undef"` if the underlying `epoll_pwait()` method returned an error. If the `epoll_pwait()` was interrupted by a signal, then 0 is returned instead.

## SEE ALSO

- •

  Linux::Epoll - O(1) multiplexing for Linux

- •

  IO::Async::Loop::Poll - use IO::Async with [**poll**(2)](/poll/2.md)

## AUTHOR

Paul Evans \<leonerd@leonerd.org.uk\>