VirtualBox

source: vbox/trunk/include/iprt/once.h@ 33516

Last change on this file since 33516 was 33262, checked in by vboxsync, 14 years ago

RTOnce: Avoid allocating anything when there are no races.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 4.3 KB
Line 
1/** @file
2 * IPRT - Execute Once.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_once_h
27#define ___iprt_once_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#include <iprt/err.h>
32
33RT_C_DECLS_BEGIN
34
35/** @defgroup grp_rt_once RTOnce - Execute Once
36 * @ingroup grp_rt
37 * @{
38 */
39
40/**
41 * Execute once structure.
42 *
43 * This is typically a global variable that is statically initialized
44 * by RTONCE_INITIALIZER.
45 */
46typedef struct RTONCE
47{
48 /** Event semaphore that the other guys are blocking on. */
49 RTSEMEVENTMULTI volatile hEventMulti;
50 /** Reference counter for hEventMulti. */
51 int32_t volatile cEventRefs;
52 /** -1 when uninitialized, 1 when initializing (busy) and 2 when done. */
53 int32_t volatile iState;
54 /** The return code of pfnOnce. */
55 int32_t volatile rc;
56} RTONCE;
57/** Pointer to a execute once struct. */
58typedef RTONCE *PRTONCE;
59
60/**
61 * The execute once statemachine.
62 */
63typedef enum RTONCESTATE
64{
65 /** RTOnce() has not been called.
66 * Next: NO_SEM */
67 RTONCESTATE_UNINITIALIZED = 1,
68 /** RTOnce() is busy, no race.
69 * Next: CREATING_SEM, DONE */
70 RTONCESTATE_BUSY_NO_SEM,
71 /** More than one RTOnce() caller is busy.
72 * Next: BUSY_HAVE_SEM, BUSY_SPIN, DONE_CREATING_SEM, DONE */
73 RTONCESTATE_BUSY_CREATING_SEM,
74 /** More than one RTOnce() caller, the first is busy, the others are
75 * waiting.
76 * Next: DONE */
77 RTONCESTATE_BUSY_HAVE_SEM,
78 /** More than one RTOnce() caller, the first is busy, the others failed to
79 * create a semaphore and are spinning.
80 * Next: DONE */
81 RTONCESTATE_BUSY_SPIN,
82 /** More than one RTOnce() caller, the first has completed, the others
83 * are busy creating the semaphore.
84 * Next: DONE_HAVE_SEM */
85 RTONCESTATE_DONE_CREATING_SEM,
86 /** More than one RTOnce() caller, the first is busy grabbing the
87 * semaphore, while the others are waiting.
88 * Next: DONE */
89 RTONCESTATE_DONE_HAVE_SEM,
90 /** The execute once stuff has completed. */
91 RTONCESTATE_DONE = 16
92} RTONCESTATE;
93
94/** Static initializer for RTONCE variables. */
95#define RTONCE_INITIALIZER { NIL_RTSEMEVENTMULTI, 0, RTONCESTATE_UNINITIALIZED, VERR_INTERNAL_ERROR }
96
97
98/**
99 * Callback that gets executed once.
100 *
101 * @returns IPRT style status code, RTOnce returns this.
102 *
103 * @param pvUser1 The first user parameter.
104 * @param pvUser2 The second user parameter.
105 */
106typedef DECLCALLBACK(int32_t) FNRTONCE(void *pvUser1, void *pvUser2);
107/** Pointer to a FNRTONCE. */
108typedef FNRTONCE *PFNRTONCE;
109
110/**
111 * Serializes execution of the pfnOnce function, making sure it's
112 * executed exactly once and that nobody returns from RTOnce before
113 * it has executed successfully.
114 *
115 * @returns IPRT like status code returned by pfnOnce.
116 *
117 * @param pOnce Pointer to the execute once variable.
118 * @param pfnOnce The function to executed once.
119 * @param pvUser1 The first user parameter for pfnOnce.
120 * @param pvUser2 The second user parameter for pfnOnce.
121 */
122RTDECL(int) RTOnce(PRTONCE pOnce, PFNRTONCE pfnOnce, void *pvUser1, void *pvUser2);
123
124/**
125 * Resets an execute once variable.
126 *
127 * The caller is responsible for making sure there are no concurrent accesses to
128 * the execute once variable.
129 *
130 * @param pOnce Pointer to the execute once variable.
131 */
132RTDECL(void) RTOnceReset(PRTONCE pOnce);
133
134/** @} */
135
136RT_C_DECLS_END
137
138#endif
139
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette