1*b1cdbd2cSJim Jagielski /**************************************************************
2*b1cdbd2cSJim Jagielski  *
3*b1cdbd2cSJim Jagielski  * Licensed to the Apache Software Foundation (ASF) under one
4*b1cdbd2cSJim Jagielski  * or more contributor license agreements.  See the NOTICE file
5*b1cdbd2cSJim Jagielski  * distributed with this work for additional information
6*b1cdbd2cSJim Jagielski  * regarding copyright ownership.  The ASF licenses this file
7*b1cdbd2cSJim Jagielski  * to you under the Apache License, Version 2.0 (the
8*b1cdbd2cSJim Jagielski  * "License"); you may not use this file except in compliance
9*b1cdbd2cSJim Jagielski  * with the License.  You may obtain a copy of the License at
10*b1cdbd2cSJim Jagielski  *
11*b1cdbd2cSJim Jagielski  *   http://www.apache.org/licenses/LICENSE-2.0
12*b1cdbd2cSJim Jagielski  *
13*b1cdbd2cSJim Jagielski  * Unless required by applicable law or agreed to in writing,
14*b1cdbd2cSJim Jagielski  * software distributed under the License is distributed on an
15*b1cdbd2cSJim Jagielski  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16*b1cdbd2cSJim Jagielski  * KIND, either express or implied.  See the License for the
17*b1cdbd2cSJim Jagielski  * specific language governing permissions and limitations
18*b1cdbd2cSJim Jagielski  * under the License.
19*b1cdbd2cSJim Jagielski  *
20*b1cdbd2cSJim Jagielski  *************************************************************/
21*b1cdbd2cSJim Jagielski 
22*b1cdbd2cSJim Jagielski 
23*b1cdbd2cSJim Jagielski 
24*b1cdbd2cSJim Jagielski #if !defined INCLUDED_OSL_DOUBLECHECKEDLOCKING_H
25*b1cdbd2cSJim Jagielski #define INCLUDED_OSL_DOUBLECHECKEDLOCKING_H
26*b1cdbd2cSJim Jagielski 
27*b1cdbd2cSJim Jagielski #if defined __cplusplus
28*b1cdbd2cSJim Jagielski extern "C" {
29*b1cdbd2cSJim Jagielski #endif /* __cplusplus */
30*b1cdbd2cSJim Jagielski 
31*b1cdbd2cSJim Jagielski /** A platform specific macro needed to make double-checked locking work.
32*b1cdbd2cSJim Jagielski 
33*b1cdbd2cSJim Jagielski     See
34*b1cdbd2cSJim Jagielski     <http://www.cs.umd.edu/~pugh/java/memoryModel/DoubleCheckedLocking.html>
35*b1cdbd2cSJim Jagielski     for a description of double-checked locking, why it is broken, and how it
36*b1cdbd2cSJim Jagielski     can be fixed.  On platforms where it is necessary, this macro will expand
37*b1cdbd2cSJim Jagielski     to some memory barrier instruction.  On many platforms, double-checked
38*b1cdbd2cSJim Jagielski     locking works as it is, though, so on those platforms this macro will be
39*b1cdbd2cSJim Jagielski     empty.  This is a macro instead of a (C++ inline) function to allow for
40*b1cdbd2cSJim Jagielski     maximum performance in both C and C++.
41*b1cdbd2cSJim Jagielski 
42*b1cdbd2cSJim Jagielski     If possible, use the rtl_Instance template instead of explicitly spelling
43*b1cdbd2cSJim Jagielski     out the double-checked locking pattern.  There are few cases where you
44*b1cdbd2cSJim Jagielski     will have to spell it out explicitly (e.g., the logic of a certain
45*b1cdbd2cSJim Jagielski     instance of the pattern is too complex to be mapped to the template, or
46*b1cdbd2cSJim Jagielski     some compiler refuses to compile a template instantiation due to internal
47*b1cdbd2cSJim Jagielski     compiler errors), though, and you should always call this macro at the
48*b1cdbd2cSJim Jagielski     right places then:
49*b1cdbd2cSJim Jagielski 
50*b1cdbd2cSJim Jagielski       static T * pInstance = 0;
51*b1cdbd2cSJim Jagielski 
52*b1cdbd2cSJim Jagielski       T * p = pInstance;
53*b1cdbd2cSJim Jagielski       if (!p)
54*b1cdbd2cSJim Jagielski       {
55*b1cdbd2cSJim Jagielski           Guard aGuard(aMutex);
56*b1cdbd2cSJim Jagielski           p = pInstance;
57*b1cdbd2cSJim Jagielski           if (!p)
58*b1cdbd2cSJim Jagielski           {
59*b1cdbd2cSJim Jagielski               p = ...;
60*b1cdbd2cSJim Jagielski               OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER();
61*b1cdbd2cSJim Jagielski               pInstance = p;
62*b1cdbd2cSJim Jagielski           }
63*b1cdbd2cSJim Jagielski       }
64*b1cdbd2cSJim Jagielski       else
65*b1cdbd2cSJim Jagielski           OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER();
66*b1cdbd2cSJim Jagielski       return p;
67*b1cdbd2cSJim Jagielski 
68*b1cdbd2cSJim Jagielski     One extra advantage of this macro is that it makes it easier to find all
69*b1cdbd2cSJim Jagielski     places where double-checked locking is used.
70*b1cdbd2cSJim Jagielski  */
71*b1cdbd2cSJim Jagielski #define OSL_DOUBLE_CHECKED_LOCKING_MEMORY_BARRIER() /* empty */
72*b1cdbd2cSJim Jagielski 
73*b1cdbd2cSJim Jagielski #if defined __cplusplus
74*b1cdbd2cSJim Jagielski }
75*b1cdbd2cSJim Jagielski #endif /* __cplusplus */
76*b1cdbd2cSJim Jagielski 
77*b1cdbd2cSJim Jagielski #endif /* INCLUDED_OSL_DOUBLECHECKEDLOCKING_H */
78