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

# dispatch\_group\_async\_f(3)

group blocks submitted to queues

Part of [dispatch\_group\_create(3)](/dispatch_group_create/3.md).

## NAME

**dispatch\_group\_create**, **dispatch\_group\_async**, **dispatch\_group\_wait**, **dispatch\_group\_notify** – group blocks submitted to queues

## SYNOPSIS

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

*dispatch\_group\_t*\

**dispatch\_group\_create**(*void*);

*void*\

**dispatch\_group\_enter**(*dispatch\_group\_t group*);

*void*\

**dispatch\_group\_leave**(*dispatch\_group\_t group*);

*long*\

**dispatch\_group\_wait**(*dispatch\_group\_t group*, *dispatch\_time\_t timeout*);

*void*\

**dispatch\_group\_notify**(*dispatch\_group\_t group*, *dispatch\_queue\_t queue*, *void (^block)(void)*);

*void*\

**dispatch\_group\_notify\_f**(*dispatch\_group\_t group*, *dispatch\_queue\_t queue*, *void \*context*, *void (\*function)(void \*)*);

*void*\

**dispatch\_group\_async**(*dispatch\_group\_t group*, *dispatch\_queue\_t queue*, *void (^block)(void)*);

*void*\

**dispatch\_group\_async\_f**(*dispatch\_group\_t group*, *dispatch\_queue\_t queue*, *void \*context*, *void (\*function)(void \*)*);

## DESCRIPTION

A dispatch group is an association of one or more blocks submitted to dispatch queues for asynchronous invocation. Applications may use dispatch groups to wait for the completion of blocks associated with the group.

The **dispatch\_group\_create**() function returns a new and empty dispatch group.

The **dispatch\_group\_enter**() and **dispatch\_group\_leave**() functions update the number of blocks running within a group.

The **dispatch\_group\_wait**() function waits until all blocks associated with the *group* have completed, or until the specified *timeout* has elapsed. If the *group* becomes empty within the specified amount of time, the function will return zero indicating success. Otherwise, a non-zero return code will be returned. When *DISPATCH\_TIME\_FOREVER* is passed as the *timeout*, calls to this function will wait an unlimited amount of time until the group becomes empty and the return value is always zero.

The **dispatch\_group\_notify**() function provides asynchronous notification of the completion of the blocks associated with the *group* by submitting the *block* to the specified *queue* once all blocks associated with the *group* have completed. The system holds a reference to the dispatch group while an asynchronous notification is pending, therefore it is valid to release the *group* after setting a notification block. The group will be empty at the time the notification block is submitted to the target queue. The group may either be released with **dispatch\_release**() or reused for additional operations.

The **dispatch\_group\_async**() convenience function behaves like so:

```
void
dispatch_group_async(dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block)
{
	dispatch_retain(group);
	dispatch_group_enter(group);
	dispatch_async(queue, ^{
		block();
		dispatch_group_leave(group);
		dispatch_release(group);
	});
}
```

## RETURN VALUE

The **dispatch\_group\_create**() function returns NULL on failure and non-NULL on success.

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

## MEMORY MODEL

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

## FUNDAMENTALS

The **dispatch\_group\_async**() and **dispatch\_group\_notify**() functions are wrappers around **dispatch\_group\_async\_f**() and **dispatch\_group\_notify\_f**() respectively.

## SEE ALSO

[dispatch(3)](/dispatch/3.md), [dispatch\_async(3)](/dispatch_async/3.md), [dispatch\_object(3)](/dispatch_object/3.md), [dispatch\_queue\_create(3)](/dispatch_queue_create/3.md), [dispatch\_semaphore\_create(3)](/dispatch_semaphore_create/3.md), [dispatch\_time(3)](/dispatch_time/3.md)