once.h revision e64031e20c39650a7bc902a3e1aba613b9415dee
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * IPRT - Execute Once.
e64031e20c39650a7bc902a3e1aba613b9415deevboxsync * Copyright (C) 2006-2007 Oracle Corporation
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * available from http://www.virtualbox.org. This file is free software;
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * you can redistribute it and/or modify it under the terms of the GNU
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * General Public License (GPL) as published by the Free Software
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * The contents of this file may alternatively be used under the terms
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * of the Common Development and Distribution License Version 1.0
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * VirtualBox OSE distribution, in which case the provisions of the
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * CDDL are applicable instead of those of the GPL.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * You may elect to license modified versions of this file under the
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * terms and conditions of either the GPL or the CDDL or both.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync/** @defgroup grp_rt_once RTOnce - Execute Once
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @ingroup grp_rt
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * Execute once structure.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * This is typically a global variable that is statically initialized
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * by RTONCE_INITIALIZER.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsynctypedef struct RTONCE
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync /** Event semaphore that the other guys are blocking on. */
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync /** Reference counter for hEventMulti. */
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync /** -1 when uninitialized, 1 when initializing (busy) and 2 when done. */
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync /** The return code of pfnOnce. */
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync/** Pointer to a execute once struct. */
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync/** Static initializer for RTONCE variables. */
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync#define RTONCE_INITIALIZER { NIL_RTSEMEVENTMULTI, 0, -1, VERR_INTERNAL_ERROR }
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * Callback that gets executed once.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @returns IPRT style status code, RTOnce returns this.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @param pvUser1 The first user parameter.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @param pvUser2 The second user parameter.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsynctypedef DECLCALLBACK(int32_t) FNRTONCE(void *pvUser1, void *pvUser2);
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync/** Pointer to a FNRTONCE. */
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * Serializes execution of the pfnOnce function, making sure it's
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * executed exactly once and that nobody returns from RTOnce before
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * it has executed successfully.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @returns IPRT like status code returned by pfnOnce.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @param pOnce Pointer to the execute once variable.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @param pfnOnce The function to executed once.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @param pvUser1 The first user parameter for pfnOnce.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsync * @param pvUser2 The second user parameter for pfnOnce.
33b0e5fd502b10034575ffa7c8a30c6816222ce2vboxsyncRTDECL(int) RTOnce(PRTONCE pOnce, PFNRTONCE pfnOnce, void *pvUser1, void *pvUser2);
6e59cff536e8de93f15fa1fb6b46d0ee01e06829vboxsync * Resets an execute once variable.
6e59cff536e8de93f15fa1fb6b46d0ee01e06829vboxsync * The caller is responsible for making sure there are no concurrent accesses to
6e59cff536e8de93f15fa1fb6b46d0ee01e06829vboxsync * the execute once variable.
6e59cff536e8de93f15fa1fb6b46d0ee01e06829vboxsync * @param pOnce Pointer to the execute once variable.