JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
Threading.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved.
3 * Copyright (c) 2012 JogAmp Community. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met:
8 *
9 * - Redistribution of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * - Redistribution in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * Neither the name of Sun Microsystems, Inc. or the names of
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * This software is provided "AS IS," without a warranty of any kind. ALL
21 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
22 * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
23 * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
24 * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
25 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
26 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
27 * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
28 * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
29 * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
30 * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
31 * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
32 *
33 * You acknowledge that this software is not designed or intended for use
34 * in the design, construction, operation or maintenance of any nuclear
35 * facility.
36 *
37 * Sun gratefully acknowledges that this software was originally authored
38 * and developed by Kenneth Bradley Russell and Christopher John Kline.
39 */
40
41package com.jogamp.opengl;
42
43import jogamp.opengl.ThreadingImpl;
44
45/** This API provides access to the threading model for the implementation of
46 the classes in this package.
47
48 <P>
49
50 OpenGL is specified as a thread-safe API, but in practice there
51 are multithreading-related issues on most, if not all, of the
52 platforms which support it. For example, some OpenGL
53 implementations do not behave well when one context is made
54 current first on one thread, released, and then made current on a
55 second thread, although this is legal according to the OpenGL
56 specification. On other platforms there are other problems.
57
58 <P>
59
60 Due to these limitations, and due to the inherent multithreading
61 in the Java platform (in particular, in the Abstract Window
62 Toolkit), it is often necessary to limit the multithreading
63 occurring in the typical application using the OpenGL API.
64
65 <P>
66
67 In the current reference implementation, for instance, multithreading
68 has been limited by
69 forcing all OpenGL-related work for GLAutoDrawables on to a single
70 thread. In other words, if an application uses only the
71 GLAutoDrawable and GLEventListener callback mechanism, it is
72 guaranteed to have the most correct single-threaded behavior on
73 all platforms.
74
75 <P>
76
77 Applications using the GLContext makeCurrent/release API directly
78 will inherently break this single-threaded model, as these methods
79 require that the OpenGL context be made current on the current
80 thread immediately. For applications wishing to integrate better
81 with an implementation that uses the single-threaded model, this
82 class provides public access to the mechanism used by the implementation.
83
84 <P>
85
86 Users can execute Runnables on the
87 internal thread used for performing OpenGL work, and query whether
88 the current thread is already this thread. Using these mechanisms
89 the user can move work from the current thread on to the internal
90 OpenGL thread if desired.
91
92 <P>
93
94 This class also provides mechanisms for querying whether this
95 internal serialization of OpenGL work is in effect, and a
96 programmatic way of disabling it. In the current reference
97 implementation it is enabled by default, although it could be
98 disabled in the future if OpenGL drivers become more robust on
99 all platforms.
100
101 <P>
102
103 In addition to specifying programmatically whether the single
104 thread for OpenGL work is enabled, users may switch it on and off
105 using the system property <code>jogl.1thread</code>. Valid values
106 for this system property are:
107
108 <PRE>
109 -Djogl.1thread=false Disable single-threading of OpenGL work, hence use multithreading.
110 -Djogl.1thread=true Enable single-threading of OpenGL work (default -- on a newly-created worker thread)
111 -Djogl.1thread=auto Select default single-threading behavior (currently on)
112 -Djogl.1thread=awt Enable single-threading of OpenGL work on AWT event dispatch thread (current default on all
113 platforms, and also the default behavior older releases)
114 -Djogl.1thread=worker Enable single-threading of OpenGL work on newly-created worker thread (not suitable for Mac
115 OS X or X11 platforms, and risky on Windows in applet environments)
116 </PRE>
117*/
118
119public class Threading {
120 public static enum Mode {
121 /**
122 * Full multithreaded OpenGL,
123 * i.e. any {@link Threading#invoke(boolean, Runnable, Object) invoke}
124 * {@link Threading#invokeOnOpenGLThread(boolean, Runnable) commands}
125 * will be issued on the current thread immediately.
126 */
127 MT(0),
128
129 /** Single-Threaded OpenGL on AWT EDT */
131
132 /** Single-Threaded OpenGL on dedicated worker thread. */
134
135 public final int id;
136
137 Mode(final int id){
138 this.id = id;
139 }
140 }
141
142 /** No reason to ever instantiate this class */
143 private Threading() {}
144
145 /** Returns the threading mode */
146 public static Mode getMode() {
147 return ThreadingImpl.getMode();
148 }
149
150 /** If an implementation of the com.jogamp.opengl APIs offers a
151 multithreading option but the default behavior is single-threading,
152 this API provides a mechanism for end users to disable single-threading
153 in this implementation. Users are strongly discouraged from
154 calling this method unless they are aware of all of the
155 consequences and are prepared to enforce some amount of
156 threading restrictions in their applications. Disabling
157 single-threading, for example, may have unintended consequences
158 on GLAutoDrawable implementations such as GLCanvas and GLJPanel.
159 Currently there is no supported way to re-enable it
160 once disabled, partly to discourage careless use of this
161 method. This method should be called as early as possible in an
162 application. */
163 public static final void disableSingleThreading() {
164 ThreadingImpl.disableSingleThreading();
165 }
166
167 /** Indicates whether OpenGL work is being automatically forced to a
168 single thread in this implementation. */
169 public static final boolean isSingleThreaded() {
170 return ThreadingImpl.isSingleThreaded();
171 }
172
173 /** Indicates whether the current thread is the designated toolkit thread,
174 if such semantics exists. */
175 public static final boolean isToolkitThread() throws GLException {
176 return ThreadingImpl.isToolkitThread();
177 }
178
179 /**
180 * Indicates whether the current thread is capable of
181 * performing OpenGL-related work.
182 * <p>
183 * Method always returns <code>true</code>
184 * if {@link #getMode()} == {@link Mode#MT} or {@link #isSingleThreaded()} == <code>false</code>.
185 * </p>
186 */
187 public static final boolean isOpenGLThread() throws GLException {
188 return ThreadingImpl.isOpenGLThread();
189 }
190
191 /** Executes the passed Runnable on the single thread used for all
192 OpenGL work in this com.jogamp.opengl API implementation. It is
193 not specified exactly which thread is used for this
194 purpose. This method should only be called if the single-thread
195 model is in use and if the current thread is not the OpenGL
196 thread (i.e., if <code>isOpenGLThread()</code> returns
197 false). It is up to the end user to check to see whether the
198 current thread is the OpenGL thread and either execute the
199 Runnable directly or perform the work inside it.
200 **/
201 public static final void invokeOnOpenGLThread(final boolean wait, final Runnable r) throws GLException {
202 ThreadingImpl.invokeOnOpenGLThread(wait, r);
203 }
204
205 /**
206 * If not {@link #isOpenGLThread()}
207 * <b>and</b> the <code>lock</code> is not being hold by this thread,
208 * invoke Runnable <code>r</code> on the OpenGL thread via {@link #invokeOnOpenGLThread(boolean, Runnable)}.
209 * <p>
210 * Otherwise invoke Runnable <code>r</code> on the current thread.
211 * </p>
212 *
213 * @param wait set to true for waiting until Runnable <code>r</code> is finished, otherwise false.
214 * @param r the Runnable to be executed
215 * @param lock optional lock object to be tested
216 * @throws GLException
217 */
218 public static final void invoke(final boolean wait, final Runnable r, final Object lock) throws GLException {
219 if ( !isOpenGLThread() &&
220 ( null == lock || !Thread.holdsLock(lock) ) ) {
221 invokeOnOpenGLThread(wait, r);
222 } else {
223 r.run();
224 }
225 }
226}
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
This API provides access to the threading model for the implementation of the classes in this package...
Definition: Threading.java:119
static Mode getMode()
Returns the threading mode.
Definition: Threading.java:146
static final boolean isSingleThreaded()
Indicates whether OpenGL work is being automatically forced to a single thread in this implementation...
Definition: Threading.java:169
static final void disableSingleThreading()
If an implementation of the com.jogamp.opengl APIs offers a multithreading option but the default beh...
Definition: Threading.java:163
static final boolean isOpenGLThread()
Indicates whether the current thread is capable of performing OpenGL-related work.
Definition: Threading.java:187
static final void invoke(final boolean wait, final Runnable r, final Object lock)
If not isOpenGLThread() and the lock is not being hold by this thread, invoke Runnable r on the OpenG...
Definition: Threading.java:218
static final void invokeOnOpenGLThread(final boolean wait, final Runnable r)
Executes the passed Runnable on the single thread used for all OpenGL work in this com....
Definition: Threading.java:201
static final boolean isToolkitThread()
Indicates whether the current thread is the designated toolkit thread, if such semantics exists.
Definition: Threading.java:175
ST_WORKER
Single-Threaded OpenGL on dedicated worker thread.
Definition: Threading.java:133
MT
Full multithreaded OpenGL, i.e.
Definition: Threading.java:127
ST_AWT
Single-Threaded OpenGL on AWT EDT.
Definition: Threading.java:130