once.h revision a438caaf732f7839dc66b4f8dad672527845a003
/** @file
* IPRT - Execute Once.
*/
/*
* Copyright (C) 2006-2012 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___iprt_once_h
#define ___iprt_once_h
/** @defgroup grp_rt_once RTOnce - Execute Once
* @ingroup grp_rt
* @{
*/
/**
* Callback that gets executed once.
*
* @returns IPRT style status code, RTOnce returns this.
*
* @param pvUser The user parameter.
*/
/** Pointer to a FNRTONCE. */
/**
*
* @param pvUser The user parameter.
* @param fLazyCleanUpOk Indicates whether lazy clean-up is OK (see
* initterm.h).
*/
/** Pointer to a FNRTONCE. */
typedef FNRTONCECLEANUP *PFNRTONCECLEANUP;
/**
* Execute once structure.
*
* This is typically a global variable that is statically initialized
* by RTONCE_INITIALIZER.
*/
typedef struct RTONCE
{
/** Event semaphore that the other guys are blocking on. */
RTSEMEVENTMULTI volatile hEventMulti;
/** Reference counter for hEventMulti. */
int32_t volatile cEventRefs;
/** See RTONCESTATE. */
/** The return code of pfnOnce. */
/** Pointer to the clean-up function. */
/** Argument to hand to the clean-up function. */
void *pvUser;
/** Clean-up list entry. */
} RTONCE;
/** Pointer to a execute once struct. */
/**
* The execute once statemachine.
*/
typedef enum RTONCESTATE
{
/** RTOnce() has not been called.
* Next: NO_SEM */
/** RTOnce() is busy, no race.
* Next: CREATING_SEM, DONE */
/** More than one RTOnce() caller is busy.
* Next: BUSY_HAVE_SEM, BUSY_SPIN, DONE_CREATING_SEM, DONE */
/** More than one RTOnce() caller, the first is busy, the others are
* waiting.
* Next: DONE */
/** More than one RTOnce() caller, the first is busy, the others failed to
* create a semaphore and are spinning.
* Next: DONE */
/** More than one RTOnce() caller, the first has completed, the others
* are busy creating the semaphore.
* Next: DONE_HAVE_SEM */
/** More than one RTOnce() caller, the first is busy grabbing the
* semaphore, while the others are waiting.
* Next: DONE */
/** The execute once stuff has completed. */
RTONCESTATE_DONE = 16
} RTONCESTATE;
/** Static initializer for RTONCE variables. */
#define RTONCE_INITIALIZER \
{ NIL_RTSEMEVENTMULTI, 0, RTONCESTATE_UNINITIALIZED, VERR_INTERNAL_ERROR, NULL, NULL, { NULL, NULL } }
/**
* 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 pfnCleanUp The function that will be doing the cleaning up.
* Optional.
* @param pvUser The user parameter for pfnOnce.
*/
/**
* 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 pvUser The user parameter for pfnOnce.
*/
{
|| iState == RTONCESTATE_DONE_HAVE_SEM ))
}
/**
* Execute pfnOnce once and register a termination clean-up callback.
*
* 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 pfnCleanUp The function that will be doing the cleaning up.
* @param pvUser The user parameter for pfnOnce.
*/
DECLINLINE(int) RTOnceEx(PRTONCE pOnce, PFNRTONCE pfnOnce, PFNRTONCECLEANUP pfnCleanUp, void *pvUser)
{
|| iState == RTONCESTATE_DONE_HAVE_SEM ))
}
/**
* 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.
*/
/** @} */
#endif