---
name: "callout_handle_init"
section: "9"
platform: "linux"
package: "freebsd-manpages"
version: "6.0-5"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/callout_handle_init"
---

# callout\_handle\_init(9)

execute a function after a specified length of time

## NAME

**timeout**, **untimeout**, **callout\_handle\_init**, **callout\_init**, **callout\_init\_mtx**, **callout\_stop**, **callout\_drain**, **callout\_reset**, **callout\_pending**, **callout\_active**, **callout\_deactivate** – execute a function after a specified length of time

## SYNOPSIS

**#include \<sys/types.h\>**

**#include \<sys/systm.h\>**

```
typedef void timeout_t (void *);
```

*struct* *callout\_handle*\

**timeout**(*timeout\_t \*func*, *void \*arg*, *int ticks*);

*void*\

**callout\_handle\_init**(*struct callout\_handle \*handle*);

```
struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
```

*void*\

**untimeout**(*timeout\_t \*func*, *void \*arg*, *struct callout\_handle handle*);

*void*\

**callout\_init**(*struct callout \*c*, *int mpsafe*);

*void*\

**callout\_init\_mtx**(*struct callout \*c*, *struct mtx \*mtx*, *int flags*);

*int*\

**callout\_stop**(*struct callout \*c*);

*int*\

**callout\_drain**(*struct callout \*c*);

*int*\

**callout\_reset**(*struct callout \*c*, *int ticks*, *timeout\_t \*func*, *void \*arg*);

*int*\

**callout\_pending**(*struct callout \*c*);

*int*\

**callout\_active**(*struct callout \*c*);

**callout\_deactivate**(*struct callout \*c*);

## DESCRIPTION

The function **timeout**() schedules a call to the function given by the argument *func* to take place after *ticks*/hz seconds. Non-positive values of *ticks* are silently converted to the value ‘1’. *func* should be a pointer to a function that takes a *void*, *\** argument. Upon invocation, *func* will receive *arg* as its only argument. The return value from **timeout**() is a *struct* *callout\_handle* which can be used in conjunction with the **untimeout**() function to request that a scheduled timeout be canceled. The **timeout**() call is the old style and new code should use the **callout\_\***() functions.

The function **callout\_handle\_init**() can be used to initialize a handle to a state which will cause any calls to untimeout with that handle to return with no side effects.

Assigning a callout handle the value of **CALLOUT\_HANDLE\_INITIALIZER**() performs the same function as **callout\_handle\_init**() and is provided for use on statically declared or global callout handles.

The function **untimeout**() cancels the timeout associated with *handle* using the *func* and *arg* arguments to validate the handle. If the handle does not correspond to a timeout with the function *func* taking the argument *arg* no action is taken. *handle* must be initialized by a previous call to **timeout**(), **callout\_handle\_init**(), or assigned the value of **CALLOUT\_HANDLE\_INITIALIZER**(*&handle*) before being passed to **untimeout**(). The behavior of calling untimeout without a previously initialized handle is undefined. The **untimeout**() call is the old style and new code should use the **callout\_\***() functions.

As handles are recycled by the system, it is possible (although unlikely) that a handle from one invocation of **timeout**() may match the handle of another invocation of **timeout**() if both calls used the same function pointer and argument, and the first timeout is expired or canceled before the second call. The timeout facility offers O(1) running time for **timeout**() and **untimeout**(). Timeouts are executed from **softclock**() with the *Giant* lock held. Thus they are protected from re-entrancy.

The functions **callout\_init**(), **callout\_init\_mtx**(), **callout\_stop**(), **callout\_drain**() and **callout\_reset**() are low-level routines for clients who wish to allocate their own callout structures.

The function **callout\_init**() initializes a callout so it can be passed to **callout\_stop**(), **callout\_drain**() or **callout\_reset**() without any side effects. If the *mpsafe* argument is zero, the callout structure is not considered to be “multi-processor safe”; that is, the Giant lock will be acquired before calling the callout function, and released when the callout function returns.

The **callout\_init\_mtx**() function may be used as an alternative to **callout\_init**(). The parameter *mtx* specifies a mutex that is to be acquired by the callout subsystem before calling the callout function, and released when the callout function returns. The following *flags* may be specified:

- CALLOUT\_RETURNUNLOCKED

  The callout function will release *mtx* itself, so the callout subsystem should not attempt to unlock it after the callout function returns.

The function **callout\_stop**() cancels a callout if it is currently pending. If the callout is pending, then **callout\_stop**() will return a non-zero value. If the callout is not set, has already been serviced or is currently being serviced, then zero will be returned. If the callout has an associated mutex, then that mutex must be held when this function is called.

The function **callout\_drain**() is identical to **callout\_stop**() except that it will wait for the callout to be completed if it is already in progress. This function MUST NOT be called while holding any locks on which the callout might block, or deadlock will result. Note that if the callout subsystem has already begun processing this callout, then the callout function may be invoked during the execution of **callout\_drain**(). However, the callout subsystem does guarantee that the callout will be fully stopped before **callout\_drain**() returns.

The function **callout\_reset**() first performs the equivalent of **callout\_stop**() to disestablish the callout, and then establishes a new callout in the same manner as **timeout**(). If there was already a pending callout and it was rescheduled, then **callout\_reset**() will return a non-zero value. If the callout has an associated mutex, then that mutex must be held when this function is called.

The macros **callout\_pending**(), **callout\_active**() and **callout\_deactivate**() provide access to the current state of the callout. Careful use of these macros can avoid many of the race conditions that are inherent in asynchronous timer facilities; see Avoiding Race Conditions below for further details. The **callout\_pending**() macro checks whether a callout is *pending*; a callout is considered *pending* when a timeout has been set but the time has not yet arrived. Note that once the timeout time arrives and the callout subsystem starts to process this callout, **callout\_pending**() will return FALSE even though the callout function may not have finished (or even begun) executing. The **callout\_active**() macro checks whether a callout is marked as *active*, and the **callout\_deactivate**() macro clears the callout's *active* flag. The callout subsystem marks a callout as *active* when a timeout is set and it clears the *active* flag in **callout\_stop**() and **callout\_drain**(), but it *does* *not* clear it when a callout expires normally via the execution of the callout function.

### Avoiding Race Conditions

The callout subsystem invokes callout functions from its own timer context. Without some kind of synchronization it is possible that a callout function will be invoked concurrently with an attempt to stop or reset the callout by another thread. In particular, since callout functions typically acquire a mutex as their first action, the callout function may have already been invoked, but be blocked waiting for that mutex at the time that another thread tries to reset or stop the callout.

The callout subsystem provides a number of mechanisms to address these synchronization concerns:

1. If the callout has an associated mutex that was specified using the **callout\_init\_mtx**() function (or implicitly specified as the *Giant* mutex using **callout\_init**() with *mpsafe* set to FALSE), then this mutex is used to avoid the race conditions. The associated mutex must be acquired by the caller before calling **callout\_stop**() or **callout\_reset**() and it is guaranteed that the callout will be correctly stopped or reset as expected. Note that it is still necessary to use **callout\_drain**() before destroying the callout or its associated mutex.

2. The return value from **callout\_stop**() and **callout\_reset**() indicates whether or not the callout was removed. If it is known that the callout was set and the callout function has not yet executed, then a return value of FALSE indicates that the callout function is about to be called. For example:

   ```
   if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
   	if (callout_stop(&sc->sc_callout)) {
   		sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
   		/* successfully stopped */
   	} else {
   		/*
   		 * callout has expired and callout
   		 * function is about to be executed
   		 */
   	}
   }
   ```

3. The **callout\_pending**(), **callout\_active**() and **callout\_deactivate**() macros can be used together to work around the race conditions. When a callout's timeout is set, the callout subsystem marks the callout as both *active* and *pending*. When the timeout time arrives, the callout subsystem begins processing the callout by first clearing the *pending* flag. It then invokes the callout function without changing the *active* flag, and does not clear the *active* flag even after the callout function returns. The mechanism described here requires the callout function itself to clear the *active* flag using the **callout\_deactivate**() macro. The **callout\_stop**() and **callout\_drain**() functions always clear both the *active* and *pending* flags before returning.

   The callout function should first check the *pending* flag and return without action if **callout\_pending**() returns TRUE. This indicates that the callout was rescheduled using **callout\_reset**() just before the callout function was invoked. If **callout\_active**() returns FALSE then the callout function should also return without action. This indicates that the callout has been stopped. Finally, the callout function should call **callout\_deactivate**() to clear the *active* flag. For example:

   ```
   mtx_lock(&sc->sc_mtx);
   if (callout_pending(&sc->sc_callout)) {
   	/* callout was reset */
   	mtx_unlock(&sc->sc_mtx);
   	return;
   }
   if (!callout_active(&sc->sc_callout)) {
   	/* callout was stopped */
   	mtx_unlock(&sc->sc_mtx);
   	return;
   }
   callout_deactivate(&sc->sc_callout);
   /* rest of callout function */
   ```

   Together with appropriate synchronization, such as the mutex used above, this approach permits the **callout\_stop**() and **callout\_reset**() functions to be used at any time without races. For example:

   ```
   mtx_lock(&sc->sc_mtx);
   callout_stop(&sc->sc_callout);
   /* The callout is effectively stopped now. */
   ```

   If the callout is still pending then these functions operate normally, but if processing of the callout has already begun then the tests in the callout function cause it to return without further action. Synchronization between the callout function and other code ensures that stopping or resetting the callout will never be attempted while the callout function is past the **callout\_deactivate**() call.

   The above technique additionally ensures that the *active* flag always reflects whether the callout is effectively enabled or disabled. If **callout\_active**() returns false, then the callout is effectively disabled, since even if the callout subsystem is actually just about to invoke the callout function, the callout function will return without action.

There is one final race condition that must be considered when a callout is being stopped for the last time. In this case it may not be safe to let the callout function itself detect that the callout was stopped, since it may need to access data objects that have already been destroyed or recycled. To ensure that the callout is completely finished, a call to **callout\_drain**() should be used.

## RETURN VALUES

The **timeout**() function returns a *struct* *callout\_handle* that can be passed to **untimeout**(). The **callout\_stop**() and **callout\_drain**() functions return non-zero if the callout was still pending when it was called or zero otherwise.

## HISTORY

The current timeout and untimeout routines are based on the work of Adam M. Costello and George Varghese, published in a technical report entitled and modified slightly for inclusion in FreeBSD by Justin T. Gibbs. The original work on the data structures used in this implementation was published by G. Varghese and A. Lauck in the paper in the The current implementation replaces the long standing BSD linked list callout mechanism which offered O(n) insertion and removal running time but did not generate or require handles for untimeout operations.