---
name: "dispatch_semaphore_create"
section: "3"
platform: "linux"
package: "libdispatch"
version: "6.2.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/dispatch_semaphore_create"
---

# dispatch\_semaphore\_create(3)

synchronized counting semaphore

## NAME

**dispatch\_semaphore\_create**, **dispatch\_semaphore\_signal**, **dispatch\_semaphore\_wait** – synchronized counting semaphore

## SYNOPSIS

**#include \<dispatch/dispatch.h\>**

*dispatch\_semaphore\_t*\

**dispatch\_semaphore\_create**(*long count*);

*long*\

**dispatch\_semaphore\_signal**(*dispatch\_semaphore\_t semaphore*);

*long*\

**dispatch\_semaphore\_wait**(*dispatch\_semaphore\_t semaphore*, *dispatch\_time\_t timeout*);

## DESCRIPTION

Dispatch semaphores are used to synchronize threads.

The **dispatch\_semaphore\_wait**() function decrements the semaphore. If the resulting value is less than zero, it waits for a signal from a thread that increments the semaphore by calling **dispatch\_semaphore\_signal**() before returning. The *timeout* parameter is creatable with the [dispatch\_time(3)](/dispatch_time/3.md) or [dispatch\_walltime(3)](/dispatch_walltime/3.md) functions. If the timeout is reached without a signal being received, the semaphore is re-incremented before the function returns.

The **dispatch\_semaphore\_signal**() function increments the counting semaphore. If the previous value was less than zero, it wakes one of the threads that are waiting in **dispatch\_semaphore\_wait**() before returning.

## COMPLETION SYNCHRONIZATION

If the *count* parameter is equal to zero, then the semaphore is useful for synchronizing completion of work. For example:

```
sema = dispatch_semaphore_create(0);
dispatch_async(queue, ^{
	foo();
	dispatch_semaphore_signal(sema);
});
bar();
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
```

## FINITE RESOURCE POOL

If the *count* parameter is greater than zero, then the semaphore is useful for managing a finite pool of resources. For example, a library that wants to limit Unix descriptor usage:

```
sema = dispatch_semaphore_create(getdtablesize() / 4);
```

At each Unix FD allocation:

```
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
fd = open("/etc/services", O_RDONLY);
```

When each FD is closed:

```
close(fd);
dispatch_semaphore_signal(sema);
```

## RETURN VALUES

The **dispatch\_semaphore\_create**() function returns NULL if no memory is available or if the *count* parameter is less than zero.

The **dispatch\_semaphore\_signal**() function returns non-zero when a thread is woken. Otherwise, zero is returned.

The **dispatch\_semaphore\_wait**() function returns zero upon success and non-zero after the timeout expires. If the timeout is DISPATCH\_TIME\_FOREVER, then **dispatch\_semaphore\_wait**() waits forever and always returns zero.

## MEMORY MODEL

Dispatch semaphores are retained and released via calls to **dispatch\_retain**() and **dispatch\_release**().

## CAVEATS

Unbalanced dispatch semaphores cannot be released. For a given semaphore, calls to **dispatch\_semaphore\_signal**() and **dispatch\_semaphore\_wait**() must be balanced before **dispatch\_release**() is called on it.

## SEE ALSO

[dispatch(3)](/dispatch/3.md), [dispatch\_object(3)](/dispatch_object/3.md)