com.lts.ipc.semaphore
Class SemaphoreNative

java.lang.Object
  com.lts.ipc.semaphore.SemaphoreNative

public class SemaphoreNative
extends java.lang.Object

An internal class that provides an interface into the system for implementing semaphores.

Exceptions

To keep the native methods as simple as possible, the exceptions thrown in response to error conditions signal the nature of the error using integer codes. The codes are defined by the class constants whose names start with "ERROR_". For example, ERROR_UNKNOWN_HANDLE is used if the platform does not recognize the handle passed to it.

Author:

cnh

Field Summary

protected static java.lang.Boolean	ourSupportsGetValue Does this particular native implementation support getting a semaphore's value?
protected static java.lang.Boolean	ourSupportsSetValue Does this particular native implementation support setting a semaphore's value other than calling decrement methods?
static int	RESULT_ACCESS_DENIED Access to the semaphore was denied when a particular operation was attempted.
static int	RESULT_NOT_IMPLEMENTED The requested method is not implemented by the native layer.
static int	RESULT_PLATFORM_ERROR The semaphore operation failed for a reason that is specific to the platform.
static int	RESULT_SUCCESS Native routines should return this to signal that the routine executed without problems.
static int	RESULT_TIMEOUT A value returned by the decrement method to signal that the method failed because the semaphore value was less than 1 and the specified timeout elapsed.
static int	RESULT_TOO_MANY_INCREMENTS The semaphore has been incremented too many times.
static int	RESULT_UNKNOWN_ERROR The semaphore operation failed for an unanticipated reason.
static int	RESULT_UNKNOWN_HANDLE The semaphore operation failed because the native platform does not recognize the handle used.

Constructor Summary

SemaphoreNative()

Method Summary

static void	connect(SemaphoreResult result, java.lang.String name, int initialValue) Connect to the underlying semaphore, creating it if it does not already exist.
static void	createResult(SemaphoreResult result, java.lang.String name, int maxValue, int initialValue)
static void	decrement(SemaphoreResult result, long handle, long timeout) Decrease the value of the semaphore by 1 if it is available; if not available wait at least the specified period of time for it to become available.
static int	getValue(SemaphoreResult result, long handle) Gets the current value of the semaphore.
static void	increment(SemaphoreResult result, long handle) Increase the value of the semaphore by 1.
static void	linkTest()
static int	setValue(SemaphoreResult result, long handle, int value) Set the value of the semaphore, without regards to other processes.
static boolean	supportsGetValue()
static boolean	supportsSetValue()

Methods inherited from class java.lang.Object

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

Field Detail

ourSupportsGetValue

protected static java.lang.Boolean ourSupportsGetValue

Does this particular native implementation support getting a semaphore's value?

ourSupportsSetValue

protected static java.lang.Boolean ourSupportsSetValue

Does this particular native implementation support setting a semaphore's value other than calling decrement methods?

RESULT_SUCCESS

public static final int RESULT_SUCCESS

Native routines should return this to signal that the routine executed without problems.

See Also:

Constant Field Values

RESULT_UNKNOWN_ERROR

public static final int RESULT_UNKNOWN_ERROR

The semaphore operation failed for an unanticipated reason.

See Also:

Constant Field Values

RESULT_PLATFORM_ERROR

public static final int RESULT_PLATFORM_ERROR

The semaphore operation failed for a reason that is specific to the platform.

See Also:

Constant Field Values

RESULT_UNKNOWN_HANDLE

public static final int RESULT_UNKNOWN_HANDLE

The semaphore operation failed because the native platform does not recognize the handle used.

See Also:

Constant Field Values

RESULT_TIMEOUT

public static final int RESULT_TIMEOUT

A value returned by the decrement method to signal that the method failed because the semaphore value was less than 1 and the specified timeout elapsed.

See Also:

Constant Field Values

RESULT_ACCESS_DENIED

public static final int RESULT_ACCESS_DENIED

Access to the semaphore was denied when a particular operation was attempted.

See Also:

Constant Field Values

RESULT_NOT_IMPLEMENTED

public static final int RESULT_NOT_IMPLEMENTED

The requested method is not implemented by the native layer.

See Also:

Constant Field Values

RESULT_TOO_MANY_INCREMENTS

public static final int RESULT_TOO_MANY_INCREMENTS

The semaphore has been incremented too many times.

See Also:

Constant Field Values

Constructor Detail

SemaphoreNative

public SemaphoreNative()

Method Detail

connect

public static void connect(SemaphoreResult result,
                           java.lang.String name,
                           int initialValue)

Connect to the underlying semaphore, creating it if it does not already exist.

The return value will be greater than 0 if the method was successful. This indicates that the value can be used in future calls to this classes methods.

If the return value is less than 0, then the native method failed. Multiplying the return value by -1 should produce a result that corresponds to one of the return codes defined by this class. That is, the absolute value should match one of the RESULT_ constants.

The return value should never be equal to 0.

Parameters:

name - The logical name of the semaphore.

initialValue - The initial value of the semaphore.

increment

public static void increment(SemaphoreResult result,
                             long handle)

Increase the value of the semaphore by 1.

Parameters:

handle - A logical value that the operating system uses to identify the semaphore.

decrement

public static void decrement(SemaphoreResult result,
                             long handle,
                             long timeout)

Decrease the value of the semaphore by 1 if it is available; if not available wait at least the specified period of time for it to become available.

The value used for handle should be one that is returned by the connect method.

The native method always checks to see if the semaphore is available. The only question is whether or not the method will wait for the semaphore if it is not currently available.

If the timeout is less than or equal to zero, the method will not wait for the semaphore to become available. If the semaphore is currently available, then it will decrement it, but if it is not available then the method returns immediately with a return code of RESULT_TIMEOUT.

If the timeout is greater than zero, the method will wait some unspecified period of time that is greater than or equal to the specified timeout for the semaphore to become available. If the semaphore is currently available, the method decrements it and returns. If the semaphore is not available, then the method waits some unspecified period of time for it to become available. If the semaphore becomes available, the method decrements it and returns RESULT_SUCCESS. If the semaphore does not become available in the period of time, the method returns RESULT_TIMEOUT.

The underlying operating system may not provide the requested resolution for nanoseconds. Generally speaking, the resolution should be at least 1 millisecond.

At present, the method returns some value other than DECREMENT_TIMEOUT if it fails for some other reason, such as the semaphore does not exist.

Parameters:

handle - Which semaphore to use.

timeout - The amount of time, in nanoseconds, to wait for the semaphore to become available if it is not currently available.

getValue

public static int getValue(SemaphoreResult result,
                           long handle)

Gets the current value of the semaphore.

The method returns 0 or greater on success and a negative value on failure. If the value indicates success, the return value is also the value of the semaphore. If negative, the absolute value corresponds to one the the RESULT_ constants.

Parameters:

handle - The semaphore to query.

Returns:

See description.

supportsGetValue

public static boolean supportsGetValue()

setValue

public static int setValue(SemaphoreResult result,
                           long handle,
                           int value)

Set the value of the semaphore, without regards to other processes.

This method replaces whatever value the semaphore had with the value passed to the method.

Parameters:

handle - The handle corresponding the semaphore to modify.

value - The new value for the semaphore.

Returns:

RESULT_SUCCESS on success, otherwise a different RESULT_ code.

supportsSetValue

public static boolean supportsSetValue()

createResult

public static void createResult(SemaphoreResult result,
                                java.lang.String name,
                                int maxValue,
                                int initialValue)

linkTest

public static void linkTest()