---
name: "dispatch_semaphore_wait"
section: "3"
platform: "linux"
package: "libdispatch-dev"
version: "0~svn197-3.2"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/dispatch_semaphore_create"
---

# dispatch\_semaphore\_wait(3)

synchronized counting semaphore

Part of [dispatch\_semaphore\_create(3)](/dispatch_semaphore_create/3.md).

## 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 *timeout* parameter is creatable with the [dispatch\_time(3)](/dispatch_time/3.md) or [dispatch\_walltime(3)](/dispatch_walltime/3.md) functions.

## 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

Dispatch semaphores are strict counting semaphores. In other words, dispatch semaphores do not saturate at any particular value. Saturation can be achieved through atomic compare-and-swap logic. What follows is a saturating binary semaphore:

```
void
saturating_semaphore_signal(dispatch_semaphore_t dsema, int *sent)
{
	if (__sync_bool_compare_and_swap(sent, 0, 1)) {
		dispatch_semaphore_signal(dsema);
	}
}
void
saturating_semaphore_wait(dispatch_semaphore_t dsema, int *sent)
{
	*sent = 0;
	dispatch_semaphore_wait(dsema, DISPATCH_TIME_FOREVER);
}
```

## SEE ALSO

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