Team2890/allwpilib
4
0
Fork 0
mirror of https://github.com/wpilibsuite/allwpilib synced 2026-06-20 00:51:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

This commit adds JNI bindings for the C++ Notifier.

Browse Source 
The bindings only wrap the HAL interface, rather than the entire C++ Notifier,
as I ran into issues trying to wrap the whole Notifier (all the existing
bindings only wrap HAL components, so wrapping stuff in :wpilibc is
unexplored). As such, the new edu.wpi.first.wpilibj.Notifier is just a
re-implementation of the wpilibc/.../Notifier.cpp.

The purpose of doing this bindings is to allow Java users a better option
for running tasks which require good timing (such as control loops). The
previous method used java.util.Timer to schedule a task, causing various
issues. Although this update does improve things, Java loop timing is still
substantially worse than that of C++, and, even worse, if Java decides to call
the garbage collector at the wrong time then the loop can be delayed by
multiple milliseconds and the next iteration will be shorter to account for it
(although this particular behavior could be updated).

A few notes on individual components:
-the HAL Task.hpp and Task.cpp were modified due to compilation/linkage
 issues with the JNI bindings. Nothing substantive changed.
-NotifierJNI was added to the build files for gradle.
-HALUtil was modified to include a function for getting the length of a C
 pointer, rather than relying on it being 32-bit.

Change-Id: I966512d8a82c2a438ed8c8bbcc6cdc6ed186d0f2
This commit is contained in:
James Kuszmaul
2015-06-02 14:00:47 -04:00
parent 90f05dd31a
commit 0b7bb41b22
9 changed files with 517 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

291
wpilibj/wpilibJavaDevices/src/main/java/edu/wpi/first/wpilibj/Notifier.java Normal file
View File

@@ -0,0 +1,291 @@
package edu.wpi.first.wpilibj;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.util.concurrent.locks.Lock;
import java.util.concurrent.locks.ReentrantLock;
import java.lang.Runtime;
import edu.wpi.first.wpilibj.hal.HALUtil;
import edu.wpi.first.wpilibj.hal.NotifierJNI;
import edu.wpi.first.wpilibj.Utility;
public class Notifier {
static private class ProcessQueue implements Runnable {
public void run() {
Notifier current;
while (true) {
Notifier.queueLock.lock();
double currentTime = Utility.getFPGATime() * 1e-6;
current = Notifier.timerQueueHead;
if (current == null || current.m_expirationTime > currentTime) {
Notifier.queueLock.unlock();
break;
}
Notifier.timerQueueHead = current.m_nextEvent;
if (current.m_periodic) {
current.insertInQueue(true);
}
else {
current.m_queued = false;
}
current.m_handlerLock.lock();
Notifier.queueLock.unlock();
current.m_handler.run();
current.m_handlerLock.unlock();
}
Notifier.queueLock.lock();
Notifier.updateAlarm();
Notifier.queueLock.unlock();
}
}
// Maximum time, in seconds, that the FPGA returns before rolling over to 0.
static private final double kRolloverTime = (1l << 32) / 1e6;
// Number of instances of Notifier classes created, so that we can call
// cleanNotifier() after all the Notifiers are stopped.
static private int refcount = 0;
// The next Notifier instance which needs to be called.
static private Notifier timerQueueHead = null;
// The C pointer to the notifier object. We don't use it directly, it is just
// passed to the JNI bindings.
private static ByteBuffer m_notifier;
// The lock for the queue information (namely, timerQueueHead and the
// m_nextEvent members).
private static ReentrantLock queueLock = new ReentrantLock();
// The handler which is called by the HAL library; it handles the subsequent
// calling of the user handlers.
// This is the only Runnable actually passed to the JNI bindings.
private static ProcessQueue m_processQueue;
// The next Notifier whose handler will need to be called after this one.
private Notifier m_nextEvent = null;
// The time, in microseconds, at which the corresponding handler should be
// called. Has the same zero as Utility.getFPGATime().
private double m_expirationTime = 0;
// The handler passed in by the user which should be called at the appropriate
// interval.
private Runnable m_handler;
// Whether we are calling the handler just once or periodically.
private boolean m_periodic = false;
// If periodic, the period of the calling; if just once, stores how long it
// is until we call the handler.
private double m_period = 0;
// Whether we are currently queued to be called at m_expirationTime.
private boolean m_queued = false;
// Lock on the handler so that the handler is not called before it has
// completed. This is only relevant if the handler takes a very long time to
// complete (or the period is very short) and when everything is being
// destructed.
private ReentrantLock m_handlerLock = new ReentrantLock();
/**
* This is done to store the JVM variable in the InterruptJNI
* This is done because the HAL must have access to the JVM variable
* in order to attach the newly spawned thread when an interrupt is fired.
*/
static {
ByteBuffer status = pointer();
NotifierJNI.initializeNotifierJVM(status.asIntBuffer());
HALUtil.checkStatus(status.asIntBuffer());
}
/**
* Create a Notifier for timer event notification.
* @param handler The handler is called at the notification time which is set
* using StartSingle or StartPeriodic.
*/
public Notifier(Runnable run) {
if (refcount == 0) {
init();
}
refcount += 1;
m_handler = run;
}
protected void finalize() {
queueLock.lock();
deleteFromQueue();
// If this was the last instance of a Notifier, clean up after ourselves.
if ((--refcount) == 0) {
ByteBuffer status = pointer();
NotifierJNI.cleanNotifier(m_notifier, status.asIntBuffer());
HALUtil.checkStatus(status.asIntBuffer());
}
queueLock.unlock();
m_handlerLock.lock();
m_handlerLock = null;
}
/**
* Update the alarm hardware to reflect the current first element in the
* queue.
* Compute the time the next alarm should occur based on the current time and
* the period for the first element in the timer queue.
* WARNING: this method does not do synchronization! It must be called from
* somewhere that is taking care of synchronizing access to the queue.
*/
static protected void updateAlarm() {
if (timerQueueHead != null) {
ByteBuffer status = pointer();
NotifierJNI.updateNotifierAlarm(
m_notifier, (int)(timerQueueHead.m_expirationTime * 1e6),
status.asIntBuffer());
HALUtil.checkStatus(status.asIntBuffer());
}
}
/**
* Insert this Notifier into the timer queue in right place.
* WARNING: this method does not do synchronization! It must be called from
* somewhere that is taking care of synchronizing access to the queue.
* @param reschedule If false, the scheduled alarm is based on the current
* time and UpdateAlarm method is called which will enable the alarm if
* necessary. If true, update the time by adding the period (no drift) when
* rescheduled periodic from ProcessQueue. This ensures that the public
* methods only update the queue after finishing inserting.
*/
protected void insertInQueue(boolean reschedule) {
if (reschedule) {
m_expirationTime += m_period;
}
else {
m_expirationTime = Utility.getFPGATime() * 1e-6 + m_period;
}
if (m_expirationTime > kRolloverTime) {
m_expirationTime -= kRolloverTime;
}
if (timerQueueHead == null || timerQueueHead.m_expirationTime >= this.m_expirationTime) {
// the queue is empty or greater than the new entry
// the new entry becomes the first element
this.m_nextEvent = timerQueueHead;
timerQueueHead = this;
if (!reschedule) {
// since the first element changed, update alarm, unless we already plan to
updateAlarm();
}
}
else {
for (Notifier n = timerQueueHead; ; n = n.m_nextEvent) {
if (n.m_nextEvent == null ||
n.m_nextEvent.m_expirationTime > this.m_expirationTime) {
this.m_nextEvent = n.m_nextEvent;
n.m_nextEvent = this;
break;
}
}
}
m_queued = true;
}
/**
* Delete this Notifier from the timer queue.
* WARNING: this method does not do synchronization! It must be called from
* somewhere that is taking care of synchronizing access to the queue.
* Remove this Notifier from the timer queue and adjust the next interrupt
* time to reflect the current top of the queue.
*/
private void deleteFromQueue() {
if (m_queued) {
m_queued = false;
assert(timerQueueHead != null);
if (timerQueueHead == this) {
// removing the first item in the list - update the alarm
timerQueueHead = this.m_nextEvent;
updateAlarm();
}
else {
for (Notifier n = timerQueueHead; n != null; n = n.m_nextEvent) {
if (n.m_nextEvent == this) {
// this element is the next element from *n from the queue
// Point n around this.
n.m_nextEvent = this.m_nextEvent;
}
}
}
}
}
/**
* Register for single event notification.
* A timer event is queued for a single event after the specified delay.
* @param delay Seconds to wait before the handler is called.
*/
public void startSingle(double delay) {
queueLock.lock();
m_periodic = false;
m_period = delay;
deleteFromQueue();
insertInQueue(false);
queueLock.unlock();
}
/**
* Register for periodic event notification.
* A timer event is queued for periodic event notification. Each time the
* interrupt occurs, the event will be immediately requeued for the same time
* interval.
* @param period Period in seconds to call the handler starting one period
* after the call to this method.
*/
public void startPeriodic(double period) {
queueLock.lock();
m_periodic = true;
m_period = period;
deleteFromQueue();
insertInQueue(false);
queueLock.unlock();
}
/**
* Stop timer events from occuring.
* Stop any repeating timer events from occuring. This will also remove any
* single notification events from the queue.
* If a timer-based call to the registered handler is in progress, this
* function will block until the handler call is complete.
*/
public void stop() {
queueLock.lock();
deleteFromQueue();
queueLock.unlock();
// Wait for a currently executing handler to complete before returning from
// stop()
m_handlerLock.lock();
m_handlerLock.unlock();
}
// First time init.
protected static void init() {
ByteBuffer status = pointer();
m_processQueue = new ProcessQueue();
m_notifier = NotifierJNI.initializeNotifier(m_processQueue, status.asIntBuffer());
HALUtil.checkStatus(status.asIntBuffer());
}
// Returns a ByteBuffer with the appropriate length and endianness to pass to
// the JNI bindings.
protected static ByteBuffer pointer() {
ByteBuffer buf = ByteBuffer.allocateDirect(HALUtil.pointerSize());
buf.order(ByteOrder.LITTLE_ENDIAN);
return buf;
}
}

3
wpilibj/wpilibJavaDevices/src/main/java/edu/wpi/first/wpilibj/hal/HALUtil.java
View File

@@ -32,7 +32,7 @@ public class HALUtil extends JNIWrapper {
public static native boolean getFPGAButton(IntBuffer status);
public static native String getHALErrorMessage(int code);
public static native int getHALErrno();
public static native String getHALstrerror(int errno);
public static String getHALstrerror(){
@@ -52,4 +52,5 @@ public class HALUtil extends JNIWrapper {
}
}
public static native int pointerSize();
}

35
wpilibj/wpilibJavaDevices/src/main/java/edu/wpi/first/wpilibj/hal/NotifierJNI.java Normal file
View File

@@ -0,0 +1,35 @@
package edu.wpi.first.wpilibj.hal;
import java.nio.ByteBuffer;
import java.nio.IntBuffer;
import java.lang.Runtime;
/**
* The NotifierJNI class directly wraps the C++ HAL Notifier.
*
* This class is not meant for direct use by teams. Instead, the
* edu.wpi.first.wpilibj.Notifier class, which corresponds to the C++ Notifier
* class, should be used.
*/
public class NotifierJNI extends JNIWrapper {
/**
* Initializes the notifier to call the run() function of a Runnable.
*
* Should be called after initializeNotifierJVM().
*/
public static native ByteBuffer initializeNotifier(Runnable func, IntBuffer status);
/**
* Initializes the JVM for use by the callback. Should be called before
* anything else.
*/
public static native void initializeNotifierJVM(IntBuffer status);
/**
* Deletes the notifier object when we are done with it.
*/
public static native void cleanNotifier(ByteBuffer notifierPtr, IntBuffer status);
/**
* Sets the notifier to call the callback in another triggerTime microseconds.
*/
public static native void updateNotifierAlarm(ByteBuffer notifierPtr,
int triggerTime, IntBuffer status);
}