gomp-20050608-branch/libjava/classpath/gnu/java/awt/peer/gtk/GThreadMutex.java

   1 /* GThreadMutex.java -- Implements a mutex object for glib's gthread
   2    abstraction, for use with GNU Classpath's --portable-native-sync option.
   3    This is used in gthread-jni.c
   4
   5    Copyright (C) 2004 Free Software Foundation, Inc.
   6
   7 This file is part of GNU Classpath.
   8
   9 GNU Classpath is free software; you can redistribute it and/or modify
  10 it under the terms of the GNU General Public License as published by
  11 the Free Software Foundation; either version 2, or (at your option)
  12 any later version.
  13
  14 GNU Classpath is distributed in the hope that it will be useful, but
  15 WITHOUT ANY WARRANTY; without even the implied warranty of
  16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 General Public License for more details.
  18
  19 You should have received a copy of the GNU General Public License
  20 along with GNU Classpath; see the file COPYING.  If not, write to the
  21 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  22 02110-1301 USA.
  23
  24 Linking this library statically or dynamically with other modules is
  25 making a combined work based on this library.  Thus, the terms and
  26 conditions of the GNU General Public License cover the whole
  27 combination.
  28
  29 As a special exception, the copyright holders of this library give you
  30 permission to link this library with independent modules to produce an
  31 executable, regardless of the license terms of these independent
  32 modules, and to copy and distribute the resulting executable under
  33 terms of your choice, provided that you also meet, for each linked
  34 independent module, the terms and conditions of the license of that
  35 module.  An independent module is a module which is not derived from
  36 or based on this library.  If you modify this library, you may extend
  37 this exception to your version of the library, but you are not
  38 obligated to do so.  If you do not wish to do so, delete this
  39 exception statement from your version. */
  40
  41 package gnu.java.awt.peer.gtk;
  42
  43 /** Implements a mutex object for glib's gthread
  44     abstraction, for use with GNU Classpath's --portable-native-sync option.
  45     This is used in gthread-jni.c.
  46
  47     We use this object to implement the POSIX semantics for Mutexes.  They are
  48     needed are needed for the function vector that is passed to glib's
  49     g_thread subpackage's initialization function.
  50
  51     The GThreadMutex object itself serves as the Real Lock; if code has
  52     entered the monitor for this GThreadMutex object (in Java language, if
  53     it's synchronized on this object) then it holds the lock that this object
  54     represents.
  55
  56     @author Steven Augart
  57     May, 2004
  58
  59
  60 */
  61
  62 class GThreadMutex
  63 {
  64   /** Might "lock" be locked?  Is anyone waiting
  65       to get that lock?  How long is the queue?
  66
  67       If zero, nobody holds a lock on this GThreadMutex object, and nobody is
  68       trying to get one.   Before someone attempts to acquire a lock on this
  69       object, they must increment potentialLockers.  After they release their
  70       lock on this object, they must decrement potentialLockers.
  71
  72       Access to this field is guarded by synchronizing on the object
  73       <code>lockForPotentialLockers</code>.
  74
  75       After construction, we only access this field via JNI.
  76   */
  77   volatile int potentialLockers;
  78
  79   /** An object to synchronize to if you want to examine or modify the
  80       <code>potentialLockers</code> field.  Only hold this lock for brief
  81       moments, just long enough to check or set the value of
  82       <code>lockForPotentialLockers</code>.
  83
  84       We use this representation so that g_thread_mutex_trylock() will work
  85       with the POSIX semantics.  This is the only case in which you ever hold a
  86       lock on <code>lockForPotentialLockers</code> while trying to get another
  87       lock -- if you are the mutex_trylock() implementation, and you have just
  88       checked that <code>potentialLockers</code> has the value zero.  In that
  89       case, mutex_trylock() holds the lock on lockForPotentialLockers so that
  90       another thread calling mutex_trylock() or mutex_lock() won't increment
  91       potentialLockers after we've checked it and before we've gained the lock
  92       on the POSIX mutex.   Of course, in that case the operation of gaining
  93       the POSIX lock itself will succeed immediately, and once it has
  94       succeeded, trylock releases lockForPotentialLockers right away,
  95       incremented to 1 (one).
  96
  97       After construction, we only access this field via JNI.
  98   */
  99   Object lockForPotentialLockers;
 100
 101   GThreadMutex()
 102   {
 103     potentialLockers = 0;
 104     lockForPotentialLockers = new Object();
 105   }
 106 }
 107 // Local Variables:
 108 // c-file-style: "gnu"
 109 // End: