timer.h revision 88f2d1be3dfc08847d2cb205c079ffd8476b7f7b
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * IPRT - Timer.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * available from http://www.virtualbox.org. This file is free software;
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * you can redistribute it and/or modify it under the terms of the GNU
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * General Public License (GPL) as published by the Free Software
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * The contents of this file may alternatively be used under the terms
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * of the Common Development and Distribution License Version 1.0
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * VirtualBox OSE distribution, in which case the provisions of the
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * CDDL are applicable instead of those of the GPL.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * You may elect to license modified versions of this file under the
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * terms and conditions of either the GPL or the CDDL or both.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * additional information or have any questions.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** @defgroup grp_rt_timer RTTimer - Timer
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * The IPRT timer API provides a simple abstraction of recurring and one-shot callback timers.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Because of the great variation in the native APIs and the quality of
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * the service delivered by those native APIs, the timers are operated
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * on at best effort basis.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * All the ring-3 implementations are naturally at the mercy of the scheduler,
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * which means that the callback rate might vary quite a bit and we might skip
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * ticks. Many systems have a restriction that a process can only have one
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * timer. IPRT currently makes no efforts at multiplexing timers in those kind
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * of situations and will simply fail if you try to create more than one timer.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Things are generally better in ring-0. The implementations will use interrupt
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * time callbacks wherever available, and if not, resort to a high priority
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * kernel thread.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @ingroup grp_rt
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** Timer handle. */
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Timer callback function.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * The context this call is made in varies with different platforms and
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * kernel / user mode IPRT.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * In kernel mode a timer callback should not waste time, it shouldn't
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * waste stack and it should be prepared that some APIs might not work
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * correctly because of weird OS restrictions in this context that we
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * haven't discovered and avoided yet. Please fix those APIs so they
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * at least avoid panics and weird behaviour.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param pTimer Timer handle.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param pvUser User argument.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsynctypedef DECLCALLBACK(void) FNRTTIMER(PRTTIMER pTimer, void *pvUser);
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** Pointer to FNRTTIMER() function. */
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Create a recurring timer.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @returns iprt status code.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param ppTimer Where to store the timer handle.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param uMilliesInterval Milliseconds between the timer ticks.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * This is rounded up to the system granularity.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param pfnTimer Callback function which shall be scheduled for execution
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * on every timer tick.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param pvUser User argument for the callback.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @see RTTimerDestroy, RTTimerStop
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsyncRTDECL(int) RTTimerCreate(PRTTIMER *ppTimer, unsigned uMilliesInterval, PFNRTTIMER pfnTimer, void *pvUser);
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Create a suspended timer.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @returns iprt status code.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @retval VERR_NOT_SUPPORTED if an unsupported flag was specfied.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param ppTimer Where to store the timer handle.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param u64NanoInterval The interval between timer ticks specified in nanoseconds if it's
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * a recurring timer. This is rounded to the fit the system timer granularity.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * For one shot timers, pass 0.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param fFlags Timer flags.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param pfnTimer Callback function which shall be scheduled for execution
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * on every timer tick.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param pvUser User argument for the callback.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @see RTTimerStart, RTTimerStop, RTTimerDestroy, RTTimerGetSystemGranularity
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsyncRTDECL(int) RTTimerCreateEx(PRTTIMER *ppTimer, uint64_t u64NanoInterval, unsigned fFlags, PFNRTTIMER pfnTimer, void *pvUser);
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** @name RTTimerCreateEx flags
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** Any CPU is fine. (Must be 0.) */
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** One specific CPU */
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** All online CPUs. */
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync#define RTTIMER_FLAGS_CPU_ALL ( RTTIMER_FLAGS_CPU_MASK | RTTIMER_FLAGS_CPU_SPECIFIC )
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** CPU mask. */
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** Convert a CPU number (0-based) to RTTimerCreateEx flags.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * This will automatically OR in the RTTIMER_FLAG_CPU_SPECIFIC flag. */
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync#define RTTIMER_FLAGS_CPU(iCpu) ( (iCpu) | RTTIMER_FLAG_CPU_SPECIFIC )
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync/** Macro that validates the flags. */
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync#define RTTIMER_FLAGS_IS_VALID(fFlags) ( !((fFlags) & ((fFlags) & RTTIMER_FLAGS_CPU_SPECIFIC ? 0x1ff : 0x100)) )
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Stops and destroys a running timer.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @returns iprt status code.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param pTimer Timer to stop and destroy. NULL is ok.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Stops an active timer.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @returns IPRT status code.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @retval VERR_INVALID_HANDLE if pTimer isn't valid.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @retval VERR_TIMER_ACTIVE if the timer isn't suspended.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param pTimer The timer to activate.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @param u64First The RTTimeSystemNanoTS() for when the timer should start
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * firing (relative). If 0 is specified, the timer will fire ASAP.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @see RTTimerStop
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsyncRTDECL(int) RTTimerStart(PRTTIMER pTimer, uint64_t u64First);
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * Stops an active timer.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @returns IPRT status code.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @retval VERR_INVALID_HANDLE if pTimer isn't valid.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @retval VERR_TIMER_SUSPENDED if the timer isn't active.
beb1b4125f65953ac9ed0ba843cf6248e333d860vboxsync * @retval VERR_NOT_SUPPORTED if the IPRT implementation doesn't support stopping a timer.