---
name: "dispatch_semaphore_create"
section: "3"
platform: "macos"
package: "libdispatch"
version: "1542.100.32"
release: "macOS 26.5"
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**().

## SEE ALSO

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

## CAVEATS

Unbalanced dispatch semaphores cannot be released. For a given semaphore, the count at the time **dispatch\_release**() is called must be equal to or larger than the count the semaphore was created with. In other words, at the time of releasing the semaphore, there must have been at least as many **dispatch\_semaphore\_signal**() calls as there were successful **dispatch\_semaphore\_wait**() calls that did not timeout.