jj2000.j2k.util

Class NativeServices

java.lang.Object

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
private static int	LIB_STATE_LOADED Library load state ID indicating that the library was successfully loaded.
private static int	LIB_STATE_NOT_FOUND Library load state ID indicating that an attempt to load the library was done and that it could not be found.
private static int	LIB_STATE_NOT_LOADED Library load state ID indicating that no attept to load the library has been done yet.
private static int	libState The state of the library loading
static String	SHLIB_NAME The name of the shared library containing the implementation of the native methods: 'jj2000'.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	NativeServices() Private and only constructor, so that no class instance might be created.

Method Summary

Methods

Modifier and Type	Method and Description
private static void	checkLibrary() Checks if the library SHLIB_NAME is already loaded and attempts to load if not yet loaded.
static int	getThreadConcurrency() Returns the current concurrency level.
private static int	getThreadConcurrencyN() Calls the POSIX threads 'pthread_getconcurrency', or equivalent, function and return the result.
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.
private static void	setThreadConcurrencyN(int level) Calls the POSIX threads 'pthread_setconcurrency', or equivalent, function with 'level' as the argument.

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: 'jj2000'. The actual file name of the library is system dependent. Under UNIX it will be 'libjj2000.so', while under Windows it will be 'jj2000.dll'.

See Also:

Constant Field Values

libState

private static int libState

The state of the library loading

LIB_STATE_NOT_LOADED

private static final int LIB_STATE_NOT_LOADED

Library load state ID indicating that no attept to load the library has been done yet.

See Also:

Constant Field Values

LIB_STATE_LOADED

private static final int LIB_STATE_LOADED

Library load state ID indicating that the library was successfully loaded.

See Also:

Constant Field Values

LIB_STATE_NOT_FOUND

private static final int LIB_STATE_NOT_FOUND

Library load state ID indicating that an attempt to load the library was done and that it could not be found.

See Also:

Constant Field Values

Constructor Detail

NativeServices

private NativeServices()

Private and only constructor, so that no class instance might be created. Since all methods are static creating a class instance is useless. If called it throws an 'IllegalArgumentException'.

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.

setThreadConcurrencyN

private static void setThreadConcurrencyN(int level)

Calls the POSIX threads 'pthread_setconcurrency', or equivalent, function with 'level' as the argument.

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)

getThreadConcurrencyN

private static int getThreadConcurrencyN()

Calls the POSIX threads 'pthread_getconcurrency', or equivalent, function and return the result.

Returns:

The current concurrency level.

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.

checkLibrary

private static void checkLibrary()

Checks if the library SHLIB_NAME is already loaded and attempts to load if not yet loaded. If the library can not be found (either in a previous attempt to load it or in an attempt in this method) an 'UnsatisfiedLinkError' exception is thrown.

Throws:

UnsatisfiedLinkError - If the library SHLIB_NAME can not be found.