Tcl\_CreateTimerHandler(3) Tcl Library Procedures Tcl\_CreateTimerHandler(3)

```

```

# [NAME](#NAME)

Tcl\_CreateTimerHandler, TclCreateTimerHandlerMicroSeconds, Tcl\_DeleteTimerHandler - call a procedure at a given time

# [SYNOPSIS](#SYNOPSIS)

```
#include <tcl.h>

Tcl_TimerToken
Tcl_CreateTimerHandler(milliseconds, proc, clientData)

Tcl_TimerToken
Tcl_CreateTimerHandlerMicroSeconds(microseconds, proc, clientData)

Tcl_DeleteTimerHandler(token)
```

# [ARGUMENTS](#ARGUMENTS)

long\_long *microseconds* (in)

How many microseconds to wait before invoking *proc*.

int *milliseconds* (in)

How many milliseconds to wait before invoking *proc*.

Tcl\_TimerProc *\*proc* (in)

Procedure to invoke after *milliseconds* have elapsed.

void *\*clientData* (in)

Arbitrary one-word value to pass to *proc*.

Tcl\_TimerToken *token* (in)

Token for previously created timer handler (the return value from some previous call to **Tcl\_CreateTimerHandler**).

```
    
```

# [DESCRIPTION](#DESCRIPTION)

**Tcl\_CreateTimerHandler** arranges for *proc* to be invoked at a time *milliseconds* milliseconds in the future. **Tcl\_CreateTimerHandlerMicroseconds** arranges for *proc* to be invoked at a time *microseconds* microseconds in the future. The callback to *proc* will be made by **Tcl\_DoOneEvent**, so **Tcl\_CreateTimerHandler** is only useful in programs that dispatch events through **Tcl\_DoOneEvent** or through Tcl commands such as **vwait**. The call to *proc* may not be made at the exact time given by the parameter: it will be made at the next opportunity after that time. For example, if **Tcl\_DoOneEvent** is not called until long after the time has elapsed, or if there are other pending events to process before the call to *proc*, then the call to *proc* will be delayed.

*Proc* should have arguments and return value that match the type **Tcl\_TimerProc**:

```
typedef void Tcl_TimerProc(


        void *clientData);
```

The *clientData* parameter to *proc* is a copy of the *clientData* argument given to **Tcl\_CreateTimerHandler** when the callback was created. Typically, *clientData* points to a data structure containing application-specific information about what to do in *proc*.

Both functions return a **token**. In case of **Tcl\_CreateTimerHandlerMicroSeconds**, the return value is **NULL**, if the given time interval is to much in the future and may not be represented. This is a theoretical case, as it is in around 26 thousand years. **Tcl\_CreateTimerHandler** does not check for overflow and never returns **NULL**.

**Tcl\_DeleteTimerHandler** may be called to delete a previously created timer handler. It deletes the handler indicated by *token* so that no call to *proc* will be made; if that handler no longer exists (e.g. because the time period has already elapsed and *proc* has been invoked then **Tcl\_DeleteTimerHandler** does nothing. The tokens returned by **Tcl\_CreateTimerHandler** never have a value of NULL, so if NULL is passed to **Tcl\_DeleteTimerHandler** then the procedure does nothing.

# [SEE ALSO](#SEE_ALSO)

[after(n)](/man/os/tcl/after.n), [Tcl\_CreateFileHandler(3)](/man/os/tcl/Tcl_CreateFileHandler.3), [Tcl\_DoWhenIdle(3)](/man/os/tcl/Tcl_DoWhenIdle.3)

# [KEYWORDS](#KEYWORDS)

callback, clock, handler, timer

7.5 Tcl

---

Document: TclCreateTimerHandlerMicroSeconds(3) from tcl 9.1.0-r2 (Chainguard OS)
Source: https://downloads.sourceforge.net/project/tcl/Tcl/9.1.0/tcl9.1.0-src.tar.gz