Team2890/allwpilib
4
0
Fork 0
mirror of https://github.com/wpilibsuite/allwpilib synced 2026-06-24 01:31:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

[wpilib] Clean up Notifier (#5630)

Browse Source 
The user-facing docs were simplified, SetHandler() was renamed to
SetCallback(), and the internal documentation was synchronized.
This commit is contained in:
Tyler Veness
2023-09-15 19:59:03 -07:00
committed by GitHub
parent 4bac4dd0f4
commit 12e2043b77
3 changed files with 148 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
wpilibc/src/main/native/cpp/Notifier.cpp
View File

@@ -17,11 +17,11 @@
using namespace frc;
Notifier::Notifier(std::function<void()> handler) {
if (!handler) {
throw FRC_MakeError(err::NullParameter, "handler");
Notifier::Notifier(std::function<void()> callback) {
if (!callback) {
throw FRC_MakeError(err::NullParameter, "callback");
}
m_handler = handler;
m_callback = callback;
int32_t status = 0;
m_notifier = HAL_InitializeNotifier(&status);
FRC_CheckErrorStatus(status, "InitializeNotifier");
@@ -38,32 +38,32 @@ Notifier::Notifier(std::function<void()> handler) {
break;
}
std::function<void()> handler;
std::function<void()> callback;
{
std::scoped_lock lock(m_processMutex);
handler = m_handler;
callback = m_callback;
if (m_periodic) {
m_expirationTime += m_period;
UpdateAlarm();
} else {
// need to update the alarm to cause it to wait again
// Need to update the alarm to cause it to wait again
UpdateAlarm(UINT64_MAX);
}
}
// call callback
if (handler) {
handler();
// Call callback
if (callback) {
callback();
}
}
});
}
Notifier::Notifier(int priority, std::function<void()> handler) {
if (!handler) {
throw FRC_MakeError(err::NullParameter, "handler");
Notifier::Notifier(int priority, std::function<void()> callback) {
if (!callback) {
throw FRC_MakeError(err::NullParameter, "callback");
}
m_handler = handler;
m_callback = callback;
int32_t status = 0;
m_notifier = HAL_InitializeNotifier(&status);
FRC_CheckErrorStatus(status, "InitializeNotifier");
@@ -81,10 +81,10 @@ Notifier::Notifier(int priority, std::function<void()> handler) {
break;
}
std::function<void()> handler;
std::function<void()> callback;
{
std::scoped_lock lock(m_processMutex);
handler = m_handler;
callback = m_callback;
if (m_periodic) {
m_expirationTime += m_period;
UpdateAlarm();
@@ -95,9 +95,9 @@ Notifier::Notifier(int priority, std::function<void()> handler) {
}
// call callback
if (handler) {
if (callback) {
try {
handler();
callback();
} catch (const frc::RuntimeError& e) {
e.Report();
FRC_ReportError(
@@ -123,7 +123,7 @@ Notifier::~Notifier() {
HAL_StopNotifier(handle, &status);
FRC_ReportError(status, "StopNotifier");
// Join the thread to ensure the handler has exited.
// Join the thread to ensure the callback has exited.
if (m_thread.joinable()) {
m_thread.join();
}
@@ -134,7 +134,7 @@ Notifier::~Notifier() {
Notifier::Notifier(Notifier&& rhs)
: m_thread(std::move(rhs.m_thread)),
m_notifier(rhs.m_notifier.load()),
m_handler(std::move(rhs.m_handler)),
m_callback(std::move(rhs.m_callback)),
m_expirationTime(std::move(rhs.m_expirationTime)),
m_period(std::move(rhs.m_period)),
m_periodic(std::move(rhs.m_periodic)) {
@@ -145,7 +145,7 @@ Notifier& Notifier::operator=(Notifier&& rhs) {
m_thread = std::move(rhs.m_thread);
m_notifier = rhs.m_notifier.load();
rhs.m_notifier = HAL_kInvalidHandle;
m_handler = std::move(rhs.m_handler);
m_callback = std::move(rhs.m_callback);
m_expirationTime = std::move(rhs.m_expirationTime);
m_period = std::move(rhs.m_period);
m_periodic = std::move(rhs.m_periodic);
@@ -161,9 +161,14 @@ void Notifier::SetName(std::string_view name) {
HAL_SetNotifierName(m_notifier, buf.data(), &status);
}
void Notifier::SetHandler(std::function<void()> handler) {
void Notifier::SetHandler(std::function<void()> callback) {
std::scoped_lock lock(m_processMutex);
m_handler = handler;
m_callback = callback;
}
void Notifier::SetCallback(std::function<void()> callback) {
std::scoped_lock lock(m_processMutex);
m_callback = callback;
}
void Notifier::StartSingle(units::second_t delay) {

102
wpilibc/src/main/native/include/frc/Notifier.h
View File

@@ -20,7 +20,7 @@
namespace frc {
/**
* Notifiers run a callback function on a separate thread at a specified period.
* Notifiers run a user-provided callback function on a separate thread.
*
* If StartSingle() is used, the callback will run once. If StartPeriodic() is
* used, the callback will run repeatedly with the given period until stop() is
@@ -29,21 +29,25 @@ namespace frc {
class Notifier {
public:
/**
* Create a Notifier for timer event notification.
* Create a Notifier with the given callback.
*
* @param handler The handler is called at the notification time which is set
* using StartSingle or StartPeriodic.
* Configure when the callback runs with StartSingle() or StartPeriodic().
*
* @param callback The callback to run.
*/
explicit Notifier(std::function<void()> handler);
explicit Notifier(std::function<void()> callback);
template <typename Callable, typename Arg, typename... Args>
requires std::invocable<Callable, Arg, Args...>
Notifier(Callable&& f, Arg&& arg, Args&&... args)
: Notifier(std::bind(std::forward<Callable>(f), std::forward<Arg>(arg),
template <typename Arg, typename... Args>
Notifier(std::invocable<Arg, Args...> auto&& callback, Arg&& arg,
Args&&... args)
: Notifier(std::bind(std::forward<decltype(callback)>(callback),
std::forward<Arg>(arg),
std::forward<Args>(args)...)) {}
/**
* Create a Notifier for timer event notification.
* Create a Notifier with the given callback.
*
* Configure when the callback runs with StartSingle() or StartPeriodic().
*
* This overload makes the underlying thread run with a real-time priority.
* This is useful for reducing scheduling jitter on processes which are
@@ -52,17 +56,16 @@ class Notifier {
* @param priority The FIFO real-time scheduler priority ([1..99] where a
* higher number represents higher priority). See "man 7
* sched" for more details.
* @param handler The handler is called at the notification time which is set
* using StartSingle or StartPeriodic.
* @param callback The callback to run.
*/
explicit Notifier(int priority, std::function<void()> handler);
explicit Notifier(int priority, std::function<void()> callback);
template <typename Callable, typename Arg, typename... Args>
requires std::invocable<Callable, Arg, Args...>
Notifier(int priority, Callable&& f, Arg&& arg, Args&&... args)
: Notifier(priority,
std::bind(std::forward<Callable>(f), std::forward<Arg>(arg),
std::forward<Args>(args)...)) {}
template <typename Arg, typename... Args>
Notifier(int priority, std::invocable<Arg, Args...> auto&& callback,
Arg&& arg, Args&&... args)
: Notifier(priority, std::bind(std::forward<decltype(callback)>(callback),
std::forward<Arg>(arg),
std::forward<Args>(args)...)) {}
/**
* Free the resources for a timer event.
@@ -73,51 +76,54 @@ class Notifier {
Notifier& operator=(Notifier&& rhs);
/**
* Sets the name of the notifier. Used for debugging purposes only.
* Sets the name of the notifier. Used for debugging purposes only.
*
* @param name Name
*/
void SetName(std::string_view name);
/**
* Change the handler function.
* Change the callback function.
*
* @param handler Handler
* @param callback The callback function.
* @deprecated Use SetCallback() instead.
*/
void SetHandler(std::function<void()> handler);
[[deprecated("Use SetCallback() instead.")]]
void SetHandler(std::function<void()> callback);
/**
* Register for single event notification.
* Change the callback function.
*
* A timer event is queued for a single event after the specified delay.
* @param callback The callback function.
*/
void SetCallback(std::function<void()> callback);
/**
* Run the callback once after the given delay.
*
* @param delay Amount of time to wait before the handler is called.
* @param delay Time to wait before the callback is called.
*/
void StartSingle(units::second_t delay);
/**
* Register for periodic event notification.
* Run the callback periodically with the given period.
*
* 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.
* The user-provided callback should be written so that it completes before
* the next time it's scheduled to run.
*
* The user-provided callback should be written in a nonblocking manner so the
* callback can be recalled at the next periodic event notification.
*
* @param period Period to call the handler starting one period
* after the call to this method.
* @param period Period after which to to call the callback starting one
* period after the call to this method.
*/
void StartPeriodic(units::second_t period);
/**
* Stop timer events from occurring.
* Stop further callback invocations.
*
* Stop any repeating timer events from occurring. This will also remove any
* single notification events from the queue.
* No further periodic callbacks will occur. Single invocations will also be
* cancelled if they haven't yet occurred.
*
* If a timer-based call to the registered handler is in progress, this
* function will block until the handler call is complete.
* If a callback invocation is in progress, this function will block until the
* callback is complete.
*/
void Stop();
@@ -154,22 +160,24 @@ class Notifier {
// The thread waiting on the HAL alarm
std::thread m_thread;
// Held while updating process information
// The mutex held while updating process information
wpi::mutex m_processMutex;
// HAL handle, atomic for proper destruction
// HAL handle (atomic for proper destruction)
std::atomic<HAL_NotifierHandle> m_notifier{0};
// Address of the handler
std::function<void()> m_handler;
// The user-provided callback
std::function<void()> m_callback;
// The absolute expiration time
// The time at which the callback should be called. Has the same zero as
// Timer::GetFPGATimestamp().
units::second_t m_expirationTime = 0_s;
// The relative time (either periodic or single)
// If periodic, stores the callback period; if single, stores the time until
// the callback call.
units::second_t m_period = 0_s;
// True if this is a periodic event
// True if the callback is periodic
bool m_periodic = false;
};