ucar.jpeg.jj2000.j2k.util

Class NativeServices

java.lang.Object

ucar.jpeg.jj2000.j2k.util.NativeServices

public final class NativeServices
extends Object

This class presents a collection of static methods that allow access to some native methods. It makes use of native methods to access those thread properties.

Since the methods in this class require the presence of a shared library with the name defined in SHLIB_NAME it is necessary to load it prior to making use of any such methods. All methods that require the shared library will automatically load the library if that has not been already done. The library might also be manually loaded with the 'loadLibrary()' method of this class.

This class provides only static methods. It should not be instantiated.

Currently the only native services available is settings relative to POSIX threads, which are not accessible from the Java API.

Currently the methods in this class make sense with POSIX threads only, since they access POSIX threads settings. POSIX threads are most used under UNIX and UNIX-like operating systems and are mostly referred to as "native" threads in Java Virtual Machine (JVM) implementations.

The shared library SHLIB_NAME uses functions of the POSIX thread library (i.e. 'pthread'). Calling the methods that use the 'pthread' library will most prbably cause the Java Virtual Machine (JVM) to crash if it is not using the POSIX threads, due to unsatisfied references. For instance, JVMs that use "green" threads will most certainly crash. POSIX threads are referred to as "native" threads in JVMs under UNIX operating systems.

On Operating Systems where POSIX threads are not available (typically Windows 95/98/NT/2000, MacIntosh, OS/2) there is no problem since the SHLIB_NAME, if available, will not make use of POSIX threads library functions, thus no problem should occur.

Field Summary

Fields

Modifier and Type	Field and Description
static String	SHLIB_NAME The name of the shared library containing the implementation of the native methods: 'ucar.jpeg.jj2000'.

Method Summary

Modifier and Type	Method and Description
static int	getThreadConcurrency() Returns the current concurrency level.
static boolean	loadLibrary() Loads the shared library implementing the native methods of this class and returns true on success.
static void	setThreadConcurrency(int n) Sets the concurrency level of the threading system of the Java Virtual Machine (JVM) to the specified level.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SHLIB_NAME

public static final String SHLIB_NAME

The name of the shared library containing the implementation of the native methods: 'ucar.jpeg.jj2000'. The actual file name of the library is system dependent. Under UNIX it will be 'libjj2000.so', while under Windows it will be 'ucar.jpeg.jj2000.dll'.

See Also:

Constant Field Values

Method Detail

setThreadConcurrency

public static void setThreadConcurrency(int n)

Sets the concurrency level of the threading system of the Java Virtual Machine (JVM) to the specified level. The concurrency level specifies how many threads can run in parallel on different CPUs at any given time for JVM implementations that use POSIX threads with PTHREAD_SCOPE_PROCESS scheduling scope. A concurrency level of 0 means that the operating system will automatically adjust the concurrency level depending on the number of threads blocking on system calls, but this will probably not exploit more than one CPU in multiporocessor machines. If the concurrency level if set to more than the number of available processors in the machine the performance might degrade.

For JVM implementations that use POSIX threads with PTHREAD_SCOPE_SYSTEM scheduling scope or JVM implementations that use Windows(R) threads and maybe others, setting the concurrency level has no effect. In this cases the number of CPUs that can be exploited by the JVM is not limited in principle, all CPUs are available to the JVM.

For JVM implementations that use "green" threads setting the concurrency level, and thus calling this method, makes no sense, since "green" threads are all contained in one user process and can not use multiple CPUs. In fact calling this method can result in a JVM crash is the shared library SHLIB_NAME has been compiled to use POSIX threads.

Parameters:

n - The new concurrency level to set.

Throws:

IllegalArgumentException - Concurrency level is negative

UnsatisfiedLinkError - If the shared native library implementing the functionality could not be loaded.

getThreadConcurrency

public static int getThreadConcurrency()

Returns the current concurrency level. See 'setThreadConcurrency' for details on the meaning of concurrency

Returns:

The current concurrency level

See Also:

setThreadConcurrency(int)

loadLibrary

public static boolean loadLibrary()

Loads the shared library implementing the native methods of this class and returns true on success. Multiple calls to this method after a successful call have no effect and return true. Multiple calls to this method after unsuccesful calls will make new attempts to load the library.

Returns:

True if the libary could be loaded or is already loaded. False if the library can not be found and loaded.