Class RealtimeParameters

java.lang.Object
com.codename1.realtime.RealtimeParameters
public final class RealtimeParameters extends Object

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

  • 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: 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: 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: 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: 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: 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: true to fail without real-time scheduling
      Returns

      this object, for chaining