javax.realtime
Class jRateSystem

java.lang.Object
  javax.realtime.jRateSystem

public class jRateSystem

extends Object

The class jRateSystem contains information about jRate's runtime and configuration.

Author:

Angelo Corsaro, Morgan Deters

Method Summary

static boolean	dropRootPrivileges(int uid) Permanently drop superuser privileges for this process.
static boolean	dropRootPrivileges(String username) Permanently drop superuser privileges for this process.
static MemoryArea	getHeap() Returns an instance of the singleton Heap.
static MemoryArea	getImmortalMemory() Returns an instance to the singleton ImmortalMemory.
static MemoryArea	getMethodArea() Returns an instance to the singleton MethodArea
static int	getRealtimeThreadSchedulingPolicy() Returns the scheduling policy that is used to scheduler Java Real-Time Threads.
static int	getThreadSchedulingPolicy() Returns the scheduling policy that is used to scheduler Java Threads.
static boolean	hasRTNPTL() Whether jRate was compiled with RTNPTL support.
static boolean	inRTSJComplianceMode() Determine whether jRate is currently running in RTSJ-compliance mode.
static boolean	isHeapAllocationNoisy() Queries whether heap allocations are currently noisy.
static boolean	isImmortalAllocationNoisy() Queries whether immortal allocations are currently noisy.
static boolean	isRoot() Whether jRate is currently running as root.
static void	requireRTSJCompliance() Determine whether this installation of jRate is capable of RTSJ-compliance mode.
static boolean	respectsPriority() Determine whether jRate will respect thread priorities.
static void	setNoisyHeapAllocation(boolean noisy) Sets heap allocations to be noisy or not.
static void	setNoisyImmortalAllocation(boolean noisy) Sets immortal allocations to be noisy or not.
static boolean	supportsMonitorControl() Determine whether jRate will respect specified priority inheritance and priority ceiling behaviors.

Methods inherited from class java.lang.Object

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

Method Detail

getThreadSchedulingPolicy

public static int getThreadSchedulingPolicy()

Returns the scheduling policy that is used to scheduler Java Threads.

Returns:

an int value representing the scheduling policy.

getRealtimeThreadSchedulingPolicy

public static int getRealtimeThreadSchedulingPolicy()

Returns the scheduling policy that is used to scheduler Java Real-Time Threads.

Returns:

an int value representing the scheduling policy.

getImmortalMemory

public static MemoryArea getImmortalMemory()

Returns an instance to the singleton ImmortalMemory.

Returns:

a MemoryArea value

getHeap

public static MemoryArea getHeap()

Returns an instance of the singleton Heap.

Returns:

a MemoryArea value

getMethodArea

public static MemoryArea getMethodArea()

Returns an instance to the singleton MethodArea

Returns:

a MemoryArea value

dropRootPrivileges

public static boolean dropRootPrivileges(int uid)

Permanently drop superuser privileges for this process. Sets the effective, real, and saved UIDs of the process to the given UID.

Effective UIDs are kept on a per-thread basis. Note that this is true whether using LinuxThreads (where each thread is a separate process) or NPTL (where all threads run under a single process ID). Therefore, superuser privileges are only dropped for the calling thread, not all threads that are already executing. New threads that are created and started from this thread (after dropping superuser privileges) will run as the unprivileged user. Threads that aren't running with superuser privileges may not be able to set scheduling parameters like priority, which means that not only will PriorityParameters not work, but monitor control policies may not either.

Parameters:

uid - the numeric user ID

Returns:

true if privileges were dropped; false if not running as root or if the UID argument is 0 (superuser)

Throws:

RuntimeException - something went wrong (perhaps illegal UID)

dropRootPrivileges

public static boolean dropRootPrivileges(String username)

Permanently drop superuser privileges for this process. Sets the effective, real, and saved UIDs of the process to that associated with the given username.

On Linux, threads are implemented in kernel as processes, so note that superuser privileges are only dropped for the calling thread, not all threads that are executing. New threads that are created and started from this thread (after dropping superuser privileges) will run as the unprivileged user. Threads that aren't running with superuser privileges may not be able to set scheduling parameters like priority, which means that not only will PriorityParameters not work, but neither will monitor control policies.

Parameters:

username - the username

Returns:

true if privileges were dropped; false if not running as root or if username refers to a superuser account

Throws:

RuntimeException - something went wrong (perhaps unknown username)

isRoot

public static boolean isRoot()

Whether jRate is currently running as root.

Returns:

true if jRate is currently running as the superuser; false otherwise

hasRTNPTL

public static boolean hasRTNPTL()

Whether jRate was compiled with RTNPTL support.

Returns:

true if jRate was compiled with RTNPTL support; false otherwise

See Also:

http://developer.osdl.org/dev/robustmutexes/

respectsPriority

public static boolean respectsPriority()

Determine whether jRate will respect thread priorities. This requires using a fusyn-patched kernel and RTNPTL (a patched glibc). These are available from the robustmutexes project. Standard LinuxThreads and NPTL threading libraries can allow low-priority threads to run in preference to high-priority threads when condition variables are signalled, when thread library functions are called, and in other cases. This is a separate issue than priority inheritance and priority ceiling support for locks.

This function returns true if and only if the threading library upon which jRate is running is believed to properly respect priorites in the following cases on a uniprocessor machine:

• When two threads are waiting on a lock, the highest-priority thread obtains the lock first.
• The highest-priority thread waiting on a condition variable re-acquires the associated lock when the condition variable is signalled.

On multiprocessor (or hyperthreaded) machines, lock stealing may be possible during lock transition.

Returns:

true if there is platform support for proper respect of priorities; false otherwise

supportsMonitorControl

public static boolean supportsMonitorControl()

Determine whether jRate will respect specified priority inheritance and priority ceiling behaviors. This requires using a fusyn-patched kernel and RTNPTL (a patched glibc). These are available from the robustmutexes project.

Returns:

true if there is platform support for priority inheritance and priority ceiling; false otherwise

inRTSJComplianceMode

public static boolean inRTSJComplianceMode()

Determine whether jRate is currently running in RTSJ-compliance mode. At present, jRate is not RTSJ-compliant. This method is a placeholder for future versions which will include runtime-tunable parameters that make jRate more convenient (or behave better in certain circumstances) at the cost of compliance. For now, it always returns false.

Returns:

whether jRate is running in RTSJ-compliance mode

requireRTSJCompliance

public static void requireRTSJCompliance()

Determine whether this installation of jRate is capable of RTSJ-compliance mode. At present, jRate is not RTSJ-compliant. This method is a placeholder for future versions which will include build-time parameters that may sacrifice strict compliance. For now, it always returns false.

Returns:

whether this installation of jRate is capable of being RTSJ-compliant public static boolean hasRTSJComplianceMode() { return false; } /** An application calls this method to notify the jRate runtime that RTSJ compliance is required. If jRate is not currently in RTSJ-compliance mode, an exception is thrown. If this method returns normally, RTSJ-compliance is protected; any attempted change to jRate's behavior that would result in non-compliance will throw an exception.

setNoisyHeapAllocation

public static void setNoisyHeapAllocation(boolean noisy)

Sets heap allocations to be noisy or not. When heap allocations are noisy, any allocation performed in HeapMemory causes a message to be printed, with a stack trace. NOTE: noisy allocation is only supported in debug builds of jRate; please configure jRate with --enable-debug.

setNoisyImmortalAllocation

public static void setNoisyImmortalAllocation(boolean noisy)

Sets immortal allocations to be noisy or not. When immortal allocations are noisy, any allocation performed in ImmortalMemory causes a message to be printed, with a stack trace. NOTE: noisy allocation is only supported in debug builds of jRate; please configure jRate with --enable-debug.

isHeapAllocationNoisy

public static boolean isHeapAllocationNoisy()

Queries whether heap allocations are currently noisy.

isImmortalAllocationNoisy

public static boolean isImmortalAllocationNoisy()

Queries whether immortal allocations are currently noisy.