001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package org.wpilib.hardware.hal;
006
007/**
008 * The NotifierJNI class directly wraps the C++ HAL Notifier.
009 *
010 * <p>This class is not meant for direct use by teams. Instead, the org.wpilib.system.Notifier
011 * class, which corresponds to the C++ Notifier class, should be used.
012 *
013 * @see "wpi/hal/Notifier.h"
014 */
015public class NotifierJNI extends JNIWrapper {
016  /**
017   * Creates a notifier.
018   *
019   * <p>A notifier is an timer that alarms at an initial and (optionally) repeated intervals. This
020   * can be used to make precise control loops.
021   *
022   * @return the created notifier
023   * @see "HAL_CreateNotifier"
024   */
025  public static native int createNotifier();
026
027  /**
028   * Sets the HAL notifier thread priority.
029   *
030   * <p>The HAL notifier thread is responsible for managing the system's notifier interrupt and
031   * waking up user's Notifiers when it's their time to run. Giving the HAL notifier thread
032   * real-time priority helps ensure the user's real-time Notifiers, if any, are notified to run in
033   * a timely manner.
034   *
035   * @param realTime Set to true to set a real-time priority, false for standard priority.
036   * @param priority Priority to set the thread to. For real-time, this is 1-99 with 99 being
037   *     highest. For non-real-time, this is forced to 0. See "man 7 sched" for more details.
038   * @return True on success.
039   * @see "HAL_SetNotifierThreadPriority"
040   */
041  public static native boolean setHALThreadPriority(boolean realTime, int priority);
042
043  /**
044   * Sets the name of the notifier.
045   *
046   * @param notifierHandle Notifier handle.
047   * @param name Notifier name.
048   * @see "HAL_SetNotifierName"
049   */
050  public static native void setNotifierName(int notifierHandle, String name);
051
052  /**
053   * Destroys a notifier.
054   *
055   * <p>Destruction wakes up any waiters.
056   *
057   * @param notifierHandle the notifier handle
058   * @see "HAL_DestroyNotifier"
059   */
060  public static native void destroyNotifier(int notifierHandle);
061
062  /**
063   * Updates the initial and interval alarm times for a notifier.
064   *
065   * <p>The alarmTime is an absolute time (using the WPI now() time base) if absolute is true, or
066   * relative to the current time if absolute is false.
067   *
068   * <p>If intervalTime is non-zero, the notifier will alarm periodically following alarmTime at the
069   * given interval.
070   *
071   * <p>If an absolute alarmTime is in the past, the notifier will alarm immediately.
072   *
073   * @param notifierHandle the notifier handle
074   * @param alarmTime the first alarm time (in microseconds)
075   * @param intervalTime the periodic interval time (in microseconds)
076   * @param absolute true if the alarm time is absolute
077   * @param ack true to acknowledge any prior alarm
078   * @see "HAL_SetNotifierAlarm"
079   */
080  public static native void setNotifierAlarm(
081      int notifierHandle, long alarmTime, long intervalTime, boolean absolute, boolean ack);
082
083  /**
084   * Cancels all future notifier alarms for a notifier.
085   *
086   * @param notifierHandle the notifier handle
087   * @param ack true to acknowledge any prior alarm
088   * @see "HAL_CancelNotifierAlarm"
089   */
090  public static native void cancelNotifierAlarm(int notifierHandle, boolean ack);
091
092  /**
093   * Indicates the notifier alarm has been serviced. Makes no change to future alarms.
094   *
095   * <p>One of setNotifierAlarm (with ack=true), cancelNotifierAlarm (with ack=true), or this
096   * function must be called before waiting for the next alarm.
097   *
098   * @param notifierHandle the notifier handle
099   * @see "HAL_AcknowledgeNotifierAlarm"
100   */
101  public static native void acknowledgeNotifierAlarm(int notifierHandle);
102
103  /**
104   * Gets the overrun count for a notifier.
105   *
106   * <p>An overrun occurs when a notifier's alarm is not serviced before the next scheduled alarm
107   * time.
108   *
109   * @param notifierHandle the notifier handle
110   * @return overrun count
111   */
112  public static native int getNotifierOverrun(int notifierHandle);
113
114  /** Utility class. */
115  private NotifierJNI() {}
116}