001: /*
002: * $RCSfile: NativeServices.java,v $
003: * $Revision: 1.1 $
004: * $Date: 2005/02/11 05:02:26 $
005: * $State: Exp $
006: *
007: * Class: NativeServices
008: *
009: * Description: Static methods allowing to access to some
010: * native services. It uses native methods.
011: *
012: *
013: *
014: * COPYRIGHT:
015: *
016: * This software module was originally developed by Raphaël Grosbois and
017: * Diego Santa Cruz (Swiss Federal Institute of Technology-EPFL); Joel
018: * Askelöf (Ericsson Radio Systems AB); and Bertrand Berthelot, David
019: * Bouchard, Félix Henry, Gerard Mozelle and Patrice Onno (Canon Research
020: * Centre France S.A) in the course of development of the JPEG2000
021: * standard as specified by ISO/IEC 15444 (JPEG 2000 Standard). This
022: * software module is an implementation of a part of the JPEG 2000
023: * Standard. Swiss Federal Institute of Technology-EPFL, Ericsson Radio
024: * Systems AB and Canon Research Centre France S.A (collectively JJ2000
025: * Partners) agree not to assert against ISO/IEC and users of the JPEG
026: * 2000 Standard (Users) any of their rights under the copyright, not
027: * including other intellectual property rights, for this software module
028: * with respect to the usage by ISO/IEC and Users of this software module
029: * or modifications thereof for use in hardware or software products
030: * claiming conformance to the JPEG 2000 Standard. Those intending to use
031: * this software module in hardware or software products are advised that
032: * their use may infringe existing patents. The original developers of
033: * this software module, JJ2000 Partners and ISO/IEC assume no liability
034: * for use of this software module or modifications thereof. No license
035: * or right to this software module is granted for non JPEG 2000 Standard
036: * conforming products. JJ2000 Partners have full right to use this
037: * software module for his/her own purpose, assign or donate this
038: * software module to any third party and to inhibit third parties from
039: * using this software module for non JPEG 2000 Standard conforming
040: * products. This copyright notice must be included in all copies or
041: * derivative works of this software module.
042: *
043: * Copyright (c) 1999/2000 JJ2000 Partners.
044: *
045: *
046: *
047: */
048:
049: package jj2000.j2k.util;
050:
051: /**
052: * This class presents a collection of static methods that allow access to
053: * some native methods. It makes use of native methods to access those thread
054: * properties.
055: *
056: * <P>Since the methods in this class require the presence of a shared library
057: * with the name defined in SHLIB_NAME it is necessary to load it prior to
058: * making use of any such methods. All methods that require the shared library
059: * will automatically load the library if that has not been already done. The
060: * library might also be manually loaded with the 'loadLibrary()' method of
061: * this class.
062: *
063: * <P>This class provides only static methods. It should not be instantiated.
064: *
065: * <P>Currently the only native services available is settings relative to
066: * POSIX threads, which are not accessible from the Java API.
067: *
068: * <P>Currently the methods in this class make sense with POSIX threads only,
069: * since they access POSIX threads settings. POSIX threads are most used under
070: * UNIX and UNIX-like operating systems and are mostly referred to as "native"
071: * threads in Java Virtual Machine (JVM) implementations.
072: *
073: * <P>The shared library SHLIB_NAME uses functions of the POSIX thread library
074: * (i.e. 'pthread'). Calling the methods that use the 'pthread' library will
075: * most prbably cause the Java Virtual Machine (JVM) to crash if it is not
076: * using the POSIX threads, due to unsatisfied references. For instance, JVMs
077: * that use "green" threads will most certainly crash. POSIX threads are
078: * referred to as "native" threads in JVMs under UNIX operating systems.
079: *
080: * <P>On Operating Systems where POSIX threads are not available (typically
081: * Windows 95/98/NT/2000, MacIntosh, OS/2) there is no problem since the
082: * SHLIB_NAME, if available, will not make use of POSIX threads library
083: * functions, thus no problem should occur.
084: * */
085: public final class NativeServices {
086:
087: /** The name of the shared library containing the implementation of the
088: * native methods: 'jj2000'. The actual file name of the library is system
089: * dependent. Under UNIX it will be 'libjj2000.so', while under Windows it
090: * will be 'jj2000.dll'.
091: * */
092: public static final String SHLIB_NAME = "jj2000";
093:
094: /** The state of the library loading */
095: private static int libState;
096:
097: /**
098: * Library load state ID indicating that no attept to load the library has
099: * been done yet. */
100: private final static int LIB_STATE_NOT_LOADED = 0;
101:
102: /**
103: * Library load state ID indicating that the library was successfully
104: * loaded. */
105: private final static int LIB_STATE_LOADED = 1;
106:
107: /**
108: * Library load state ID indicating that an attempt to load the library
109: * was done and that it could not be found. */
110: private final static int LIB_STATE_NOT_FOUND = 2;
111:
112: /**
113: * Private and only constructor, so that no class instance might be
114: * created. Since all methods are static creating a class instance is
115: * useless. If called it throws an 'IllegalArgumentException'.
116: * */
117: private NativeServices() {
118: throw new IllegalArgumentException(
119: "Class can not be instantiated");
120: }
121:
122: /**
123: * Sets the concurrency level of the threading system of the Java Virtual
124: * Machine (JVM) to the specified level. The concurrency level specifies
125: * how many threads can run in parallel on different CPUs at any given
126: * time for JVM implementations that use POSIX threads with
127: * PTHREAD_SCOPE_PROCESS scheduling scope. A concurrency level of 0 means
128: * that the operating system will automatically adjust the concurrency
129: * level depending on the number of threads blocking on system calls, but
130: * this will probably not exploit more than one CPU in multiporocessor
131: * machines. If the concurrency level if set to more than the number of
132: * available processors in the machine the performance might degrade.
133: *
134: * <P>For JVM implementations that use POSIX threads with
135: * PTHREAD_SCOPE_SYSTEM scheduling scope or JVM implementations that use
136: * Windows(R) threads and maybe others, setting the concurrency level has
137: * no effect. In this cases the number of CPUs that can be exploited by
138: * the JVM is not limited in principle, all CPUs are available to the JVM.
139: *
140: * <P>For JVM implementations that use "green" threads setting the
141: * concurrency level, and thus calling this method, makes no sense, since
142: * "green" threads are all contained in one user process and can not use
143: * multiple CPUs. In fact calling this method can result in a JVM crash is
144: * the shared library SHLIB_NAME has been compiled to use POSIX threads.
145: *
146: * @param n The new concurrency level to set.
147: *
148: * @exception IllegalArgumentException Concurrency level is negative
149: *
150: * @exception UnsatisfiedLinkError If the shared native library
151: * implementing the functionality could not be loaded.
152: * */
153: public static void setThreadConcurrency(int n) {
154: // Check that the library is loaded
155: checkLibrary();
156: // Check argument
157: if (n < 0)
158: throw new IllegalArgumentException();
159: // Set concurrency with native method
160: setThreadConcurrencyN(n);
161: }
162:
163: /**
164: * Calls the POSIX threads 'pthread_setconcurrency', or equivalent,
165: * function with 'level' as the argument.
166: * */
167: private static native void setThreadConcurrencyN(int level);
168:
169: /**
170: * Returns the current concurrency level. See 'setThreadConcurrency' for
171: * details on the meaning of concurrency
172: *
173: * @return The current concurrency level
174: *
175: * @see #setThreadConcurrency
176: * */
177: public static int getThreadConcurrency() {
178: // Check that the library is loaded
179: checkLibrary();
180: // Return concurrency from native method
181: return getThreadConcurrencyN();
182: }
183:
184: /**
185: * Calls the POSIX threads 'pthread_getconcurrency', or equivalent,
186: * function and return the result.
187: *
188: * @return The current concurrency level.
189: * */
190: private static native int getThreadConcurrencyN();
191:
192: /**
193: * Loads the shared library implementing the native methods of this
194: * class and returns true on success. Multiple calls to this method after
195: * a successful call have no effect and return true. Multiple calls to
196: * this method after unsuccesful calls will make new attempts to load the
197: * library.
198: *
199: * @return True if the libary could be loaded or is already loaded. False
200: * if the library can not be found and loaded.
201: * */
202: public static boolean loadLibrary() {
203: // If already loaded return true without doing anything
204: if (libState == LIB_STATE_LOADED)
205: return true;
206: // Try to load the library
207: try {
208: System.loadLibrary(SHLIB_NAME);
209: } catch (UnsatisfiedLinkError e) {
210: // Library was not found
211: libState = LIB_STATE_NOT_FOUND;
212: return false;
213: }
214: // Library was found
215: libState = LIB_STATE_LOADED;
216: return true;
217: }
218:
219: /**
220: * Checks if the library SHLIB_NAME is already loaded and attempts to load
221: * if not yet loaded. If the library can not be found (either in a
222: * previous attempt to load it or in an attempt in this method) an
223: * 'UnsatisfiedLinkError' exception is thrown.
224: *
225: * @exception UnsatisfiedLinkError If the library SHLIB_NAME can not be
226: * found.
227: * */
228: private static void checkLibrary() {
229: switch (libState) {
230: case LIB_STATE_LOADED: // Already loaded, nothing to do
231: return;
232: case LIB_STATE_NOT_LOADED: // Not yet loaded => load now
233: // If load successful break, otherwise continue to the
234: // LIB_STATE_NOT_LOADED state
235: if (loadLibrary())
236: break;
237: case LIB_STATE_NOT_FOUND: // Could not be found, throw exception
238: throw new UnsatisfiedLinkError(
239: "NativeServices: native shared "
240: + "library could not be loaded");
241: }
242: }
243:
244: }
|