once.h revision 96ae2df030763cee874d3f5ac0be07cd1f793281
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync/** @file
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * IPRT - Execute Once.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync/*
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Copyright (C) 2006-2007 Oracle Corporation
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync *
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * available from http://www.virtualbox.org. This file is free software;
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * you can redistribute it and/or modify it under the terms of the GNU
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * General Public License (GPL) as published by the Free Software
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync *
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * The contents of this file may alternatively be used under the terms
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * of the Common Development and Distribution License Version 1.0
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * VirtualBox OSE distribution, in which case the provisions of the
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * CDDL are applicable instead of those of the GPL.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync *
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * You may elect to license modified versions of this file under the
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * terms and conditions of either the GPL or the CDDL or both.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync#ifndef ___iprt_once_h
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync#define ___iprt_once_h
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync#include <iprt/cdefs.h>
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync#include <iprt/types.h>
0165172a2610650f9fcfc668901bc6c2d09144c3vboxsync#include <iprt/err.h>
0165172a2610650f9fcfc668901bc6c2d09144c3vboxsync
0165172a2610650f9fcfc668901bc6c2d09144c3vboxsyncRT_C_DECLS_BEGIN
0165172a2610650f9fcfc668901bc6c2d09144c3vboxsync
0165172a2610650f9fcfc668901bc6c2d09144c3vboxsync/** @defgroup grp_rt_once RTOnce - Execute Once
0165172a2610650f9fcfc668901bc6c2d09144c3vboxsync * @ingroup grp_rt
0165172a2610650f9fcfc668901bc6c2d09144c3vboxsync * @{
0165172a2610650f9fcfc668901bc6c2d09144c3vboxsync */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync/**
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Execute once structure.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync *
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * This is typically a global variable that is statically initialized
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * by RTONCE_INITIALIZER.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsynctypedef struct RTONCE
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync{
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** Event semaphore that the other guys are blocking on. */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTSEMEVENTMULTI volatile hEventMulti;
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** Reference counter for hEventMulti. */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync int32_t volatile cEventRefs;
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** -1 when uninitialized, 1 when initializing (busy) and 2 when done. */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync int32_t volatile iState;
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** The return code of pfnOnce. */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync int32_t volatile rc;
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync} RTONCE;
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync/** Pointer to a execute once struct. */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsynctypedef RTONCE *PRTONCE;
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync/**
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * The execute once statemachine.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsynctypedef enum RTONCESTATE
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync{
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** RTOnce() has not been called.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Next: NO_SEM */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTONCESTATE_UNINITIALIZED = 1,
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** RTOnce() is busy, no race.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Next: CREATING_SEM, DONE */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTONCESTATE_BUSY_NO_SEM,
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** More than one RTOnce() caller is busy.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Next: BUSY_HAVE_SEM, BUSY_SPIN, DONE_CREATING_SEM, DONE */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTONCESTATE_BUSY_CREATING_SEM,
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** More than one RTOnce() caller, the first is busy, the others are
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * waiting.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Next: DONE */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTONCESTATE_BUSY_HAVE_SEM,
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** More than one RTOnce() caller, the first is busy, the others failed to
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * create a semaphore and are spinning.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Next: DONE */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTONCESTATE_BUSY_SPIN,
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** More than one RTOnce() caller, the first has completed, the others
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * are busy creating the semaphore.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Next: DONE_HAVE_SEM */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTONCESTATE_DONE_CREATING_SEM,
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** More than one RTOnce() caller, the first is busy grabbing the
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * semaphore, while the others are waiting.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Next: DONE */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTONCESTATE_DONE_HAVE_SEM,
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync /** The execute once stuff has completed. */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync RTONCESTATE_DONE = 16
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync} RTONCESTATE;
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync/** Static initializer for RTONCE variables. */
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync#define RTONCE_INITIALIZER { NIL_RTSEMEVENTMULTI, 0, RTONCESTATE_UNINITIALIZED, VERR_INTERNAL_ERROR }
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync/**
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * Callback that gets executed once.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync *
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * @returns IPRT style status code, RTOnce returns this.
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync *
4338d1606b19c219ef8f200aae7558a8ea7cb796vboxsync * @param pvUser1 The first user parameter.
* @param pvUser2 The second user parameter.
*/
typedef DECLCALLBACK(int32_t) FNRTONCE(void *pvUser1, void *pvUser2);
/** Pointer to a FNRTONCE. */
typedef FNRTONCE *PFNRTONCE;
/**
* Serializes execution of the pfnOnce function, making sure it's
* executed exactly once and that nobody returns from RTOnce before
* it has executed successfully.
*
* @returns IPRT like status code returned by pfnOnce.
*
* @param pOnce Pointer to the execute once variable.
* @param pfnOnce The function to executed once.
* @param pvUser1 The first user parameter for pfnOnce.
* @param pvUser2 The second user parameter for pfnOnce.
*/
RTDECL(int) RTOnce(PRTONCE pOnce, PFNRTONCE pfnOnce, void *pvUser1, void *pvUser2);
/**
* Resets an execute once variable.
*
* The caller is responsible for making sure there are no concurrent accesses to
* the execute once variable.
*
* @param pOnce Pointer to the execute once variable.
*/
RTDECL(void) RTOnceReset(PRTONCE pOnce);
/** @} */
RT_C_DECLS_END
#endif