com.aicas.jamaica.lang

Class Scheduler

java.lang.Object

com.aicas.jamaica.lang.Scheduler

public class Scheduler
extends Object

Scheduler provides access to the Jamaica Scheduler.

Constructor Summary

Constructors

Constructor and Description
Scheduler()

Method Summary

Modifier and Type	Method and Description
static void	allocateEventsBuffer(int size) Start recording of scheduling events.
static int	microAdjustPriority(int microAdjustment) microAdjustPriority enables to slightly change the priority of the current thread such that it will have precedence over other threads with the same Java priority (+1) or other threads will have priority over this thread (-1), or it will be treated equally (0).
static int	microAdjustPriority(Thread t, int microAdjustment) microAdjustPriority enables to slightly change the priority of a running thread such that it will have precedence over other threads with the same Java priority (+1) or other threads will have priority over this thread (-1), or it will be treated equally (0).
static void	recordUserEvent(int kind, String message) Record a user-defined event with the given message
static void	recordUserEvent(String message) Record a user-defined event with the given message in color white
static void	setLeastEligible(Thread t, boolean b) This method sets the attribute that indicates that this thread has least eligibility to run.
static int	setMaxIgnorePriority(int pri) setMaxIgnorePriority sets the maximum priority that is to be ignored by the scheduler.
static int	setMaxNonStrictPriority(int pri) setMaxNonStrictPriority sets the maximum non-strict priority.
static void	startRecording(int eventMask) Start recording of scheduling events.
static int	stopRecording() Stop recording of scheduling events.
static void	useStrictPriority(boolean enabled) useStrictPriority forces the scheduler to strictly enforce the current thread's priority, i.e., if a higher priority thread is ready this thread may starve completely even if its priority is less or equal the maximum non-strict priority (see setMaxNonStrictPriority(int)).
static void	waitOnSocket(int portNum, boolean blocking) Start the events recorder such that it waits for an events recorder connect at the given port.
static void	writeResults(String filename) Write recorded results to a file.
static void	writeResultsQuiet(String filename) Write recorded results to a file.

Methods inherited from class java.lang.Object

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

Constructor Detail

Scheduler

public Scheduler()

Method Detail

allocateEventsBuffer

public static void allocateEventsBuffer(int size)

Start recording of scheduling events. If there is a recording in progress, reset the recording.

startRecording

public static void startRecording(int eventMask)

Start recording of scheduling events.

stopRecording

public static int stopRecording()

Stop recording of scheduling events.

Returns:

the number of integers recorded

writeResultsQuiet

public static void writeResultsQuiet(String filename)
                              throws IOException

Write recorded results to a file.

Throws:

IOException - if writing failed.

Parameters:

filename - the file to write

writeResults

public static void writeResults(String filename)

Write recorded results to a file. In case of an IOException, printStackTrace it to stderr.

Parameters:

filename - the file to write

recordUserEvent

public static void recordUserEvent(String message)

Record a user-defined event with the given message in color white

Parameters:

message - the event message, must be a 7-bit ASCII string.

recordUserEvent

public static void recordUserEvent(int kind,
                                   String message)

Record a user-defined event with the given message

Parameters:

kind - an id for this event's kind. This will be used to distinguish different event kinds. Currently, only the lower 16 bits are stored and display tools may use this value modulo some value (e.g. to select a color from a limited set of colors for the display of the event kind).

message - the event message, must be a 7-bit ASCII string.

useStrictPriority

public static void useStrictPriority(boolean enabled)

useStrictPriority forces the scheduler to strictly enforce the current thread's priority, i.e., if a higher priority thread is ready this thread may starve completely even if its priority is less or equal the maximum non-strict priority (see setMaxNonStrictPriority(int)). Enabling strict priority will enforce higher priority threads to always have priority over this thread. However, if the current thread's priority is less or equal to the maximum non-strict priority, it does not prevent lower priority threads from stealing the current thread's CPU. A typical application of the strict priority would be a low-priority service thread that should run without ever disturbing the execution of any other higher-priority thread (e.g., a low-priority garbage collection thread).

Parameters:

enabled - true to enable strict priorities for the current thread, false to disable strict priorities.

setMaxNonStrictPriority

public static int setMaxNonStrictPriority(int pri)

setMaxNonStrictPriority sets the maximum non-strict priority. Threads that have a Java priority that is less or equal to this priority will not use strict precedence, i.e., none of these threads will starve, even if a higher priority thread is always ready. Only if a thread with a priority higher than the maximum non-strict priority is ready to run, all threads with lower priority may starve.

Parameters:

pri - the new maximum non-strict priority. -1 to keep the maximum non-strict priority unchanged, 0 to disable non-strict priorities, 10 to enable non-strict priorities for normal Java threads only, javax.realtime.PriorityScheduler.getMaxPriority() to enable non-strict priorities for all RTSJ threads (not recommended since this will break the priority scheduling required for realtime code).

Returns:

the previous value for the maximum non strict priority.

setMaxIgnorePriority

public static int setMaxIgnorePriority(int pri)

setMaxIgnorePriority sets the maximum priority that is to be ignored by the scheduler. All Java threads with a priority less or equal to this priority will be treated equally.

Parameters:

pri - the new maximum priority to be ignored. -1 to keep the maximum ignored priority unchanged, 0 to disable ignoring priorities, 10 to treat all normal Java threads equal, javax.realtime.PriorityScheduler.getMaxPriority() to also treat RTSJ threads equally (not recommended since this will break the priority scheduling required for realtime code).

Returns:

the previous value for the maximum ignored priority.

microAdjustPriority

public static int microAdjustPriority(int microAdjustment)

microAdjustPriority enables to slightly change the priority of the current thread such that it will have precedence over other threads with the same Java priority (+1) or other threads will have priority over this thread (-1), or it will be treated equally (0).

Parameters:

microAdjustment - the priority micro adjustment. +1 to slightly increase the priority, -1 to decrease it and 0 to treat this thread equal to other threads with the same Java priority.

Returns:

the previous value for the priority micro adjustement.

microAdjustPriority

public static int microAdjustPriority(Thread t,
                                      int microAdjustment)

microAdjustPriority enables to slightly change the priority of a running thread such that it will have precedence over other threads with the same Java priority (+1) or other threads will have priority over this thread (-1), or it will be treated equally (0). This call will have no effect if the given thread t has not been started yet or has died already.

Parameters:

t - the thread whose priority micro-adjustment is to be changed.

microAdjustment - the priority micro adjustment. +1 to slightly increase the priority, -1 to decrease it and 0 to treat this thread equal to other threads with the same Java priority.

Returns:

the previous value for the priority micro adjustement. Result is Integer.MIN_VALUE in case t is not alive.

setLeastEligible

public static void setLeastEligible(Thread t,
                                    boolean b)

This method sets the attribute that indicates that this thread has least eligibility to run.

This call has no effect if the given thread t has not been started yet or has died already.

• Least eligible threads are still subject to priority inheritance: while a least eligible thread T holds a monitor that another thread S waits for and S is not least eligible, the thread T becomes at least as eligible as the waiting thread S.
• Least eligible threads are still subject to priority ceiling emulation: while a least eligible thread T holds a priority ceiling monitor M, T's eligibility is at least as high as the eligibility of any thread that has M's ceiling priority.
• Scheduling of multiple least eligible threads is governed by the timeSlice: when only least eligible threads are eligible for execution and none of their eligibilities has been raised by priority inheritance or priority ceiling emulation, then the scheduling of these threads is subject to the timeSlice that is configured.
• The native priority that is associated with least eligible threads is priMap(0), which is the same as the native priority for Java priority 1 with micro-adjustment -1.

Parameters:

t - the thread whose priority attribute 'leastEligible' is to be set

b - the new value of the thread attribute 'leastEligible' for t

waitOnSocket

public static void waitOnSocket(int portNum,
                                boolean blocking)

Start the events recorder such that it waits for an events recorder connect at the given port.