Client and backend. This class is shared: the same code is compiled into your app and into your server, so everything on this page works in both.

public final class RealtimeParameters

Object
RealtimeParameters

How a RealtimeThread is scheduled: its period, its operating-system priority, the CPU it runs on and how much it may allocate per period.

RealtimeParameters p = new RealtimeParameters()
        .setPeriodNanos(1000000L)      // 1 kHz
        .setPriority(80)
        .setCpu(3)                     // pinned, and other threads moved off it
        .setSchedulingRequired(true);  // fail rather than run at normal priority

Constructors

public RealtimeParameters()

Methods

`public long getPeriodNanos()`	The interval between releases, in nanoseconds.
`public` `RealtimeParameters setPeriodNanos(long periodNanos)`	Sets the interval between releases.
`public int getPriority()`	The operating-system priority, `SCHED_FIFO` on Linux.
`public` `RealtimeParameters setPriority(int priority)`	Sets the operating-system priority, from 1 to 99 on Linux.
`public int getCpu()`	The CPU the thread is pinned to, or -1 for none (the default).
`public` `RealtimeParameters setCpu(int cpu)`	Pins the thread to one CPU.
`public boolean isIsolateCpu()`	Whether the application’s other threads are moved off the pinned CPU.
`public` `RealtimeParameters setIsolateCpu(boolean isolateCpu)`	Sets whether the application’s other threads – the event dispatch thread, the collector, network threads – are moved off the CPU this thread is pinned to, so they never compete with it there.
`public int getAllocationBudget()`	How many allocations a period may make.
`public` `RealtimeParameters setAllocationBudget(int allocationBudget)`	Sets how many allocations each period may make before the thread fails with a `RealtimeAllocationError`.
`public boolean isSchedulingRequired()`	Whether the thread fails when real-time scheduling cannot be applied.
`public` `RealtimeParameters setSchedulingRequired(boolean schedulingRequired)`	Sets whether the thread fails, through `RealtimeTask.failed(Throwable)`, when the operating system refuses real-time scheduling – on Linux, a process without `CAP_SYS_NICE` or an `rtprio` limit.

Inherited methods

From Object

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

Constructor details

RealtimeParameters

public RealtimeParameters()

Method details

getPeriodNanos

public long getPeriodNanos()

The interval between releases, in nanoseconds. The default is one millisecond.

setPeriodNanos

public RealtimeParameters setPeriodNanos(long periodNanos)

Sets the interval between releases. Releases are absolute – each is one period after the previous one, however long the cycle ran – so the loop does not drift.

Parameters

periodNanos long: the period, at least 10 microseconds

Returns

this object, for chaining

getPriority

public int getPriority()

The operating-system priority, SCHED_FIFO on Linux. The default is 50.

setPriority

public RealtimeParameters setPriority(int priority)

Sets the operating-system priority, from 1 to 99 on Linux. A higher number preempts a lower one, and any of them preempts every normal thread, the collector’s included. Leave the top of the range to the kernel’s own interrupt threads unless the loop must preempt them.

Parameters

priority int: the priority, 1 to 99

Returns

this object, for chaining

getCpu

public int getCpu()

The CPU the thread is pinned to, or -1 for none (the default).

setCpu

public RealtimeParameters setCpu(int cpu)

Pins the thread to one CPU. Combine it with the kernel’s isolcpus= or a cpuset that keeps other processes off that CPU for the lowest latency.

Parameters

cpu int: the CPU number, or -1 for none

Returns

this object, for chaining

isIsolateCpu

public boolean isIsolateCpu()

Whether the application’s other threads are moved off the pinned CPU. The default is true.

setIsolateCpu

public RealtimeParameters setIsolateCpu(boolean isolateCpu)

Sets whether the application’s other threads – the event dispatch thread, the collector, network threads – are moved off the CPU this thread is pinned to, so they never compete with it there. Has no effect without setCpu(int).

Parameters

isolateCpu boolean: true to move the other threads off

Returns

this object, for chaining

getAllocationBudget

public int getAllocationBudget()

How many allocations a period may make. The default is zero.

setAllocationBudget

public RealtimeParameters setAllocationBudget(int allocationBudget)

Sets how many allocations each period may make before the thread fails with a RealtimeAllocationError. Zero, the default, is the setting to aim for: an allocation is a call into the collector’s slow path, whose time is not bounded the way the cycle’s own code is. A small budget is an escape hatch for a cycle that allocates on a rare path, not a way to allocate every period.

Parameters

allocationBudget int: allocations allowed per period, zero or more

Returns

this object, for chaining

isSchedulingRequired

public boolean isSchedulingRequired()

Whether the thread fails when real-time scheduling cannot be applied. The default is false.

setSchedulingRequired

public RealtimeParameters setSchedulingRequired(boolean schedulingRequired)

Sets whether the thread fails, through RealtimeTask.failed(Throwable), when the operating system refuses real-time scheduling – on Linux, a process without CAP_SYS_NICE or an rtprio limit. When false, the default, the task runs at normal priority instead, which is what a development machine and the simulator do; RealtimeThread.isSchedulingApplied() says which happened.

Parameters

schedulingRequired boolean: true to fail without real-time scheduling

Returns

this object, for chaining