src/cairo-mutex-impl-private.h

   1 /* cairo - a vector graphics library with display and print output
   2  *
   3  * Copyright © 2002 University of Southern California
   4  * Copyright © 2005,2007 Red Hat, Inc.
   5  * Copyright © 2007 Mathias Hasselmann
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it either under the terms of the GNU Lesser General Public
   9  * License version 2.1 as published by the Free Software Foundation
  10  * (the "LGPL") or, at your option, under the terms of the Mozilla
  11  * Public License Version 1.1 (the "MPL"). If you do not alter this
  12  * notice, a recipient may use your version of this file under either
  13  * the MPL or the LGPL.
  14  *
  15  * You should have received a copy of the LGPL along with this library
  16  * in the file COPYING-LGPL-2.1; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
  18  * You should have received a copy of the MPL along with this library
  19  * in the file COPYING-MPL-1.1
  20  *
  21  * The contents of this file are subject to the Mozilla Public License
  22  * Version 1.1 (the "License"); you may not use this file except in
  23  * compliance with the License. You may obtain a copy of the License at
  24  * http://www.mozilla.org/MPL/
  25  *
  26  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
  27  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  28  * the specific language governing rights and limitations.
  29  *
  30  * The Original Code is the cairo graphics library.
  31  *
  32  * The Initial Developer of the Original Code is University of Southern
  33  * California.
  34  *
  35  * Contributor(s):
  36  *      Carl D. Worth <cworth@cworth.org>
  37  *      Mathias Hasselmann <mathias.hasselmann@gmx.de>
  38  *      Behdad Esfahbod <behdad@behdad.org>
  39  */
  40
  41 #ifndef CAIRO_MUTEX_IMPL_PRIVATE_H
  42 #define CAIRO_MUTEX_IMPL_PRIVATE_H
  43
  44 #include "cairo.h"
  45
  46 #if HAVE_CONFIG_H
  47 #include "config.h"
  48 #endif
  49
  50 #if HAVE_LOCKDEP
  51 #include <lockdep.h>
  52 #endif
  53
  54 /* A fully qualified no-operation statement */
  55 #define CAIRO_MUTEX_IMPL_NOOP   do {/*no-op*/} while (0)
  56 /* And one that evaluates its argument once */
  57 #define CAIRO_MUTEX_IMPL_NOOP1(expr)        do { (void)(expr); } while (0)
  58 /* Note: 'if (expr) {}' is an alternative to '(void)(expr);' that will 'use' the
  59  * result of __attribute__((warn_used_result)) functions. */
  60
  61 /* Cairo mutex implementation:
  62  *
  63  * Any new mutex implementation needs to do the following:
  64  *
  65  * - Condition on the right header or feature.  Headers are
  66  *   preferred as eg. you still can use win32 mutex implementation
  67  *   on a win32 system even if you do not compile the win32
  68  *   surface/backend.
  69  *
  70  * - typedef #cairo_mutex_impl_t to the proper mutex type on your target
  71  *   system.  Note that you may or may not need to use a pointer,
  72  *   depending on what kinds of initialization your mutex
  73  *   implementation supports.  No trailing semicolon needed.
  74  *   You should be able to compile the following snippet (don't try
  75  *   running it):
  76  *
  77  *   <programlisting>
  78  *      cairo_mutex_impl_t _cairo_some_mutex;
  79  *   </programlisting>
  80  *
  81  * - #define %CAIRO_MUTEX_IMPL_<NAME> 1 with suitable name for your platform.  You
  82  *   can later use this symbol in cairo-system.c.
  83  *
  84  * - #define CAIRO_MUTEX_IMPL_LOCK(mutex) and CAIRO_MUTEX_IMPL_UNLOCK(mutex) to
  85  *   proper statement to lock/unlock the mutex object passed in.
  86  *   You can (and should) assume that the mutex is already
  87  *   initialized, and is-not-already-locked/is-locked,
  88  *   respectively.  Use the "do { ... } while (0)" idiom if necessary.
  89  *   No trailing semicolons are needed (in any macro you define here).
  90  *   You should be able to compile the following snippet:
  91  *
  92  *   <programlisting>
  93  *      cairo_mutex_impl_t _cairo_some_mutex;
  94  *
  95  *      if (1)
  96  *          CAIRO_MUTEX_IMPL_LOCK (_cairo_some_mutex);
  97  *      else
  98  *          CAIRO_MUTEX_IMPL_UNLOCK (_cairo_some_mutex);
  99  *   </programlisting>
 100  *
 101  * - #define %CAIRO_MUTEX_IMPL_NIL_INITIALIZER to something that can
 102  *   initialize the #cairo_mutex_impl_t type you defined.  Most of the
 103  *   time one of 0, %NULL, or {} works.  At this point
 104  *   you should be able to compile the following snippet:
 105  *
 106  *   <programlisting>
 107  *      cairo_mutex_impl_t _cairo_some_mutex = CAIRO_MUTEX_IMPL_NIL_INITIALIZER;
 108  *
 109  *      if (1)
 110  *          CAIRO_MUTEX_IMPL_LOCK (_cairo_some_mutex);
 111  *      else
 112  *          CAIRO_MUTEX_IMPL_UNLOCK (_cairo_some_mutex);
 113  *   </programlisting>
 114  *
 115  * - If the above code is not enough to initialize a mutex on
 116  *   your platform, #define CAIRO_MUTEX_IMPL_INIT(mutex) to statement
 117  *   to initialize the mutex (allocate resources, etc).  Such that
 118  *   you should be able to compile AND RUN the following snippet:
 119  *
 120  *   <programlisting>
 121  *      cairo_mutex_impl_t _cairo_some_mutex = CAIRO_MUTEX_IMPL_NIL_INITIALIZER;
 122  *
 123  *      CAIRO_MUTEX_IMPL_INIT (_cairo_some_mutex);
 124  *
 125  *      if (1)
 126  *          CAIRO_MUTEX_IMPL_LOCK (_cairo_some_mutex);
 127  *      else
 128  *          CAIRO_MUTEX_IMPL_UNLOCK (_cairo_some_mutex);
 129  *   </programlisting>
 130  *
 131  * - If you define CAIRO_MUTEX_IMPL_INIT(mutex), cairo will use it to
 132  *   initialize all static mutex'es.  If for any reason that should
 133  *   not happen (eg. %CAIRO_MUTEX_IMPL_INIT is just a faster way than
 134  *   what cairo does using %CAIRO_MUTEX_IMPL_NIL_INITIALIZER), then
 135  *   <programlisting>
 136  *      #define CAIRO_MUTEX_IMPL_INITIALIZE() CAIRO_MUTEX_IMPL_NOOP
 137  *   </programlisting>
 138  *
 139  * - If your system supports freeing a mutex object (deallocating
 140  *   resources, etc), then #define CAIRO_MUTEX_IMPL_FINI(mutex) to do
 141  *   that.
 142  *
 143  * - If you define CAIRO_MUTEX_IMPL_FINI(mutex), cairo will use it to
 144  *   define a finalizer function to finalize all static mutex'es.
 145  *   However, it's up to you to call CAIRO_MUTEX_IMPL_FINALIZE() at
 146  *   proper places, eg. when the system is unloading the cairo library.
 147  *   So, if for any reason finalizing static mutex'es is not needed
 148  *   (eg. you never call CAIRO_MUTEX_IMPL_FINALIZE()), then
 149  *   <programlisting>
 150  *      #define CAIRO_MUTEX_IMPL_FINALIZE() CAIRO_MUTEX_IMPL_NOOP
 151  *   </programlisting>
 152  *
 153  * - That is all.  If for any reason you think the above API is
 154  *   not enough to implement #cairo_mutex_impl_t on your system, please
 155  *   stop and write to the cairo mailing list about it.  DO NOT
 156  *   poke around cairo-mutex-private.h for possible solutions.
 157  */
 158
 159 #if CAIRO_NO_MUTEX
 160
 161 /* No mutexes */
 162
 163   typedef int cairo_mutex_impl_t;
 164
 165 # define CAIRO_MUTEX_IMPL_NO 1
 166 # define CAIRO_MUTEX_IMPL_INITIALIZE() CAIRO_MUTEX_IMPL_NOOP
 167 # define CAIRO_MUTEX_IMPL_LOCK(mutex) CAIRO_MUTEX_IMPL_NOOP1(mutex)
 168 # define CAIRO_MUTEX_IMPL_UNLOCK(mutex) CAIRO_MUTEX_IMPL_NOOP1(mutex)
 169 # define CAIRO_MUTEX_IMPL_NIL_INITIALIZER 0
 170
 171 # define CAIRO_MUTEX_HAS_RECURSIVE_IMPL 1
 172
 173   typedef int cairo_recursive_mutex_impl_t;
 174
 175 # define CAIRO_RECURSIVE_MUTEX_IMPL_INIT(mutex)
 176 # define CAIRO_RECURSIVE_MUTEX_IMPL_NIL_INITIALIZER 0
 177
 178 #elif defined(_WIN32) /******************************************************/
 179
 180 #define WIN32_LEAN_AND_MEAN
 181 /* We require Windows 2000 features such as ETO_PDY */
 182 #if !defined(WINVER) || (WINVER < 0x0500)
 183 # define WINVER 0x0500
 184 #endif
 185 #if !defined(_WIN32_WINNT) || (_WIN32_WINNT < 0x0500)
 186 # define _WIN32_WINNT 0x0500
 187 #endif
 188
 189 # include <windows.h>
 190
 191   typedef CRITICAL_SECTION cairo_mutex_impl_t;
 192
 193 # define CAIRO_MUTEX_IMPL_WIN32 1
 194 # define CAIRO_MUTEX_IMPL_LOCK(mutex) EnterCriticalSection (&(mutex))
 195 # define CAIRO_MUTEX_IMPL_UNLOCK(mutex) LeaveCriticalSection (&(mutex))
 196 # define CAIRO_MUTEX_IMPL_INIT(mutex) InitializeCriticalSection (&(mutex))
 197 # define CAIRO_MUTEX_IMPL_FINI(mutex) DeleteCriticalSection (&(mutex))
 198 # define CAIRO_MUTEX_IMPL_NIL_INITIALIZER { NULL, 0, 0, NULL, NULL, 0 }
 199
 200 #elif defined __OS2__ /******************************************************/
 201
 202 # define INCL_BASE
 203 # define INCL_PM
 204 # include <os2.h>
 205
 206   typedef HMTX cairo_mutex_impl_t;
 207
 208 # define CAIRO_MUTEX_IMPL_OS2 1
 209 # define CAIRO_MUTEX_IMPL_LOCK(mutex) DosRequestMutexSem(mutex, SEM_INDEFINITE_WAIT)
 210 # define CAIRO_MUTEX_IMPL_UNLOCK(mutex) DosReleaseMutexSem(mutex)
 211 # define CAIRO_MUTEX_IMPL_INIT(mutex) DosCreateMutexSem (NULL, &(mutex), 0L, FALSE)
 212 # define CAIRO_MUTEX_IMPL_FINI(mutex) DosCloseMutexSem (mutex)
 213 # define CAIRO_MUTEX_IMPL_NIL_INITIALIZER 0
 214
 215 #elif CAIRO_HAS_BEOS_SURFACE /***********************************************/
 216
 217   typedef BLocker* cairo_mutex_impl_t;
 218
 219 # define CAIRO_MUTEX_IMPL_BEOS 1
 220 # define CAIRO_MUTEX_IMPL_LOCK(mutex) (mutex)->Lock()
 221 # define CAIRO_MUTEX_IMPL_UNLOCK(mutex) (mutex)->Unlock()
 222 # define CAIRO_MUTEX_IMPL_INIT(mutex) (mutex) = new BLocker()
 223 # define CAIRO_MUTEX_IMPL_FINI(mutex) delete (mutex)
 224 # define CAIRO_MUTEX_IMPL_NIL_INITIALIZER NULL
 225
 226 #elif CAIRO_HAS_PTHREAD /* and finally if there are no native mutexes ********/
 227
 228 # include <pthread.h>
 229
 230   typedef pthread_mutex_t cairo_mutex_impl_t;
 231   typedef pthread_mutex_t cairo_recursive_mutex_impl_t;
 232
 233 # define CAIRO_MUTEX_IMPL_PTHREAD 1
 234 #if HAVE_LOCKDEP
 235 /* expose all mutexes to the validator */
 236 # define CAIRO_MUTEX_IMPL_INIT(mutex) pthread_mutex_init (&(mutex), NULL)
 237 #endif
 238 # define CAIRO_MUTEX_IMPL_LOCK(mutex) pthread_mutex_lock (&(mutex))
 239 # define CAIRO_MUTEX_IMPL_UNLOCK(mutex) pthread_mutex_unlock (&(mutex))
 240 #if HAVE_LOCKDEP
 241 # define CAIRO_MUTEX_IS_LOCKED(mutex) LOCKDEP_IS_LOCKED (&(mutex))
 242 # define CAIRO_MUTEX_IS_UNLOCKED(mutex) LOCKDEP_IS_UNLOCKED (&(mutex))
 243 #endif
 244 # define CAIRO_MUTEX_IMPL_FINI(mutex) pthread_mutex_destroy (&(mutex))
 245 #if ! HAVE_LOCKDEP
 246 # define CAIRO_MUTEX_IMPL_FINALIZE() CAIRO_MUTEX_IMPL_NOOP
 247 #endif
 248 # define CAIRO_MUTEX_IMPL_NIL_INITIALIZER PTHREAD_MUTEX_INITIALIZER
 249
 250 # define CAIRO_MUTEX_HAS_RECURSIVE_IMPL 1
 251 # define CAIRO_RECURSIVE_MUTEX_IMPL_INIT(mutex) do { \
 252     pthread_mutexattr_t attr; \
 253     pthread_mutexattr_init (&attr); \
 254     pthread_mutexattr_settype (&attr, PTHREAD_MUTEX_RECURSIVE); \
 255     pthread_mutex_init (&(mutex), &attr); \
 256     pthread_mutexattr_destroy (&attr); \
 257 } while (0)
 258 # define CAIRO_RECURSIVE_MUTEX_IMPL_NIL_INITIALIZER PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP
 259
 260 #else /**********************************************************************/
 261
 262 # error "XXX: No mutex implementation found.  Cairo will not work with multiple threads.  Define CAIRO_NO_MUTEX to 1 to acknowledge and accept this limitation and compile cairo without thread-safety support."
 263
 264 #endif
 265
 266 /* By default mutex implementations are assumed to be recursive */
 267 #if ! CAIRO_MUTEX_HAS_RECURSIVE_IMPL
 268
 269 # define CAIRO_MUTEX_HAS_RECURSIVE_IMPL 1
 270
 271   typedef cairo_mutex_impl_t cairo_recursive_mutex_impl_t;
 272
 273 # define CAIRO_RECURSIVE_MUTEX_IMPL_INIT(mutex) CAIRO_MUTEX_IMPL_INIT(mutex)
 274 # define CAIRO_RECURSIVE_MUTEX_IMPL_NIL_INITIALIZER CAIRO_MUTEX_IMPL_NIL_INITIALIZER
 275
 276 #endif
 277
 278 #endif