---
name: "Time::Out"
section: "3pm"
platform: "linux"
package: "libtime-out-perl"
version: "1.0.0-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Time::Out"
---

# Time::Out(3pm)

Easily timeout long running operations

## NAME

Time::Out - Easily timeout long running operations

## SYNOPSIS

```
  use Time::Out qw( timeout );
  timeout $timeout => sub {
    # your operation is implemented here and will be interrupted
    # if it runs for more than $timeout seconds
  };
  if ( $@ ) {
    # operation timed-out
  }
```

## DESCRIPTION

The `"Time::Out"` module provides an easy interface to [**alarm**(2)](/alarm/2.md) based timeouts.  Nested timeouts are supported. The module exports the `timeout()` function by default. The function returns whatever the code placed inside the subroutine reference returns:

```
  use Time::Out qw( timeout );
  my $result = timeout 5 => sub {
    return 7;
  };
  # $result == 7
```

If `"Time::Out"` sees that Time::HiRes has been loaded, it will use that `alarm()` function (if available) instead of the default one, allowing float timeout values to be used effectively:

```
  use Time::HiRes qw();
  use Time::Out   qw( timeout );
  timeout 3.1416 => sub {
    # ...
  };
```

## CAVEATS

- Blocking I/O on MSWin32

  [**alarm**(2)](/alarm/2.md) doesn't interrupt blocking I/O on MSWin32, so `timeout()` won't do that either.

- @\_

  One drawback to using `timeout()` is that it masks `@_` in the affected code.  This happens because the affected code is actually wrapped inside another subroutine that provides it's own `@_`. You can get around this by specifically passing your `@_` (or whatever you want for that matter) to `timeout()` as such:

  ```
    use Time::Out qw( timeout );
    sub foo {
      timeout 5, @_ => sub {
        @_;
      };
    }
    my @result = foo( 42, "Hello, World!" );
    # @result == ( 42, "Hello, World!" );
  ```

- Eval inside timeout

  If the affected code has its own exception handling using Try::Tiny for example, the catch block has to be amended in a way so that it will rethrow an exception, if it refers to a timeout:

  ```
    use Scalar::Util qw( blessed  );
    use Time::Out    qw( timeout );
    use Try::Tiny    qw( catch try );
    timeout 5, sub {
      try {
        select( undef, undef, undef, 7 );
        die "bad\n";
      } catch {
        # rethrow exception, if it refers to a timeout
        die $_ if defined blessed $_ and $_->isa( 'Time::Out::Exception' );
        # handle all other exceptions
      }
    };
  ```

## SEE ALSO

[**alarm**(2)](/alarm/2.md), Sys::AlarmCall

## AUTHORS

Sven Willenbuecher, \<sven.willenbuecher@gmx.de\>

Patrick LeBoutillier, \<patl@cpan.org\>

## COPYRIGHT AND LICENSE

This software is copyright (c) 2005-2008 Patrick LeBoutillier, 2023 by Sven Willenbuecher.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.