---
name: "Thread-5.005"
section: "3pm"
platform: "linux"
package: "perl-5.005-thread"
version: "5.005.03-7.1"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/Thread-5.005"
---

# Thread-5.005(3pm)

multithreading

## NAME

Thread - multithreading

## SYNOPSIS

```
    use Thread;
```

```
    my $t = new Thread \&start_sub, @start_args;
```

```
    $t->join;
```

```
    my $tid = Thread->self->tid;
```

```
    my $tlist = Thread->list;
```

```
    lock($scalar);
```

```
    use Thread 'async';
```

```
    use Thread 'eval';
```

## DESCRIPTION

The `Thread` module provides multithreading support for perl.

## FUNCTIONS

- new \\&start\_sub

  - new \\&start\_sub, LIST

  `new` starts a new thread of execution in the referenced subroutine. The optional list is passed as parameters to the subroutine. Execution continues in both the subroutine and the code after the `new` call.

  `new Thread` returns a thread object representing the newly created thread.\

- lock VARIABLE

  `lock` places a lock on a variable until the lock goes out of scope.  If the variable is locked by another thread, the `lock` call will block until it's available. `lock` is recursive, so multiple calls to `lock` are safe--the variable will remain locked until the outermost lock on the variable goes out of scope.

  Locks on variables only affect `lock` calls--they do *not* affect normal access to a variable. (Locks on subs are different, and covered in a bit) If you really, *really* want locks to block access, then go ahead and tie them to something and manage this yourself. This is done on purpose. While managing access to variables is a good thing, perl doesn't force you out of its living room...

  If a container object, such as a hash or array, is locked, all the elements of that container are not locked. For example, if a thread does a `lock` `@a`, any other thread doing a `lock($a[12])` won't block.

  You may also `lock` a sub, using `lock &sub`. Any calls to that sub from another thread will block until the lock is released. This behaviour is not equvalent to `use attrs qw(locked)` in the sub. `use attrs qw(locked)` serializes access to a subroutine, but allows different threads non-simultaneous access. `lock &sub`, on the other hand, will not allow *any* other thread access for the duration of the lock.

  Finally, `lock` will traverse up references exactly *one* level. `lock(\$a)` is equivalent to `lock($a)`, while `lock(\\$a)` is not.\

- async BLOCK;

  `async` creates a thread to execute the block immediately following it. This block is treated as an anonymous sub, and so must have a semi-colon after the closing brace. Like `new Thread`, `async` returns a thread object.\

- Thread-\>self

  The `Thread->self` function returns a thread object that represents the thread making the `Thread->self` call.\

- Thread-\>list

  `Thread->list` returns a list of thread objects for all running and finished but un-`join`ed threads.\

- cond\_wait VARIABLE

  The `cond_wait` function takes a **locked** variable as a parameter, unlocks the variable, and blocks until another thread does a `cond_signal` or `cond_broadcast` for that same locked variable. The variable that `cond_wait` blocked on is relocked after the `cond_wait` is satisfied. If there are multiple threads `cond_wait`ing on the same variable, all but one will reblock waiting to reaquire the lock on the variable. (So if you're only using `cond_wait` for synchronization, give up the lock as soon as possible)\

- cond\_signal VARIABLE

  The `cond_signal` function takes a locked variable as a parameter and unblocks one thread that's `cond_wait`ing on that variable. If more than one thread is blocked in a `cond_wait` on that variable, only one (and which one is indeterminate) will be unblocked.

  If there are no threads blocked in a `cond_wait` on the variable, the signal is discarded.\

- cond\_broadcast VARIABLE

  The `cond_broadcast` function works similarly to `cond_wait`. `cond_broadcast`, though, will unblock **all** the threads that are blocked in a `cond_wait` on the locked variable, rather than only one.

## METHODS

- join

  `join` waits for a thread to end and returns any values the thread exited with. `join` will block until the thread has ended, though it won't block if the thread has already terminated.

  If the thread being `join`ed `die`d, the error it died with will be returned at this time. If you don't want the thread performing the `join` to die as well, you should either wrap the `join` in an `eval` or use the `eval` thread method instead of `join`.\

- eval

  The `eval` method wraps an `eval` around a `join`, and so waits for a thread to exit, passing along any values the thread might have returned. Errors, of course, get placed into `$@`.\

- tid

  The `tid` method returns the tid of a thread. The tid is a monotonically increasing integer assigned when a thread is created. The main thread of a program will have a tid of zero, while subsequent threads will have tids assigned starting with one.

## LIMITATIONS

The sequence number used to assign tids is a simple integer, and no checking is done to make sure the tid isn't currently in use. If a program creates more than 2^32 - 1 threads in a single run, threads may be assigned duplicate tids. This limitation may be lifted in a future version of Perl.

## SEE ALSO

the *attrs* manpage, the *Thread::Queue* manpage, the *Thread::Semaphore* manpage, the *Thread::Specific* manpage.