.TH TICKIT_WATCH_TIMER_AT_EPOCH 3
.SH NAME
tickit_watch_timer_at_* \- invoke a callback at a fixed future time
.SH SYNOPSIS
.EX
.B #include <tickit.h>
.sp
.BI "typedef int " TickitCallbackFn "(Tickit *" t ", TickitEventflags " flags ,
.BI "    void *" info ", void *" user );
.sp
.BI "void *tickit_watch_timer_at_epoch(Tickit *" t ", time_t " at ,
.BI "    TickitBindFlags " flags ", TickitCallbackFn *" fn ", void *" user );
.BI "void *tickit_watch_timer_at_tv(Tickit *" t ", const struct timeval *" at ,
.BI "    TickitBindFlags " flags ", TickitCallbackFn *" fn ", void *" user );
.EE
.sp
Link with \fI\-ltickit\fP.
.SH DESCRIPTION
The \fBtickit_watch_timer_at_*\fP() family of functions register a callback function to be invoked by the toplevel event loop at a fixed time in the future. A registered callback will be invoked by a running call to \fBtickit_run\fP(3). The callback function will be invoked once, and then destroyed afterwards. Each function returns an opaque pointer value which serves to identify this instance. The \fIinfo\fP pointer will be \fBNULL\fP.
.PP
When invoked, the callback function is always passed both \fBTICKIT_EV_FIRE\fP and \fBTICKIT_EV_UNBIND\fP flags to its \fIflags\fP argument. If the callback had been registered with the \fBTICKIT_BIND_DESTROY\fP flag, then it will also be invoked with the \fBTICKIT_EV_DESTROY\fP flag if it has not yet been invoked by the time the toplevel instance is destroyed.
.PP
If cancelled by \fBtickit_watch_cancel\fP(3) the callback function is invoked with just the \fBTICKIT_EV_UNBIND\fP flag if it had been registered with \fBTICKIT_BIND_UNBIND\fP.
.SH "RETURN VALUE"
\fBtickit_watch_timer_at_epoch\fP() and \fBtickit_watch_timer_at_tv\fP() return an opaque identifier pointer.
.SH "SEE ALSO"
.BR tickit_new_stdio (3),
.BR tickit_watch_timer_after_msec (3),
.BR tickit_watch_later (3),
.BR tickit_watch_signal (3),
.BR tickit_watch_process (3),
.BR tickit_watch_cancel (3),
.BR tickit (7)