Add ability to run robot main loop in a separate thread (#1895)

Default behavior is still to run the robot main loop in the main thread.

The ability to run the robot main loop in a separate thread and add a hook
for running a different function in the main thread is needed for simulation
GUI support on some platforms.

hal/src/main/native/athena/HAL.cpp

@@ -61,6 +61,7 @@ void InitializeHAL() {
   InitializeFRCDriverStation();
   InitializeI2C();
   InitialzeInterrupts();
+  InitializeMain();
   InitializeNotifier();
   InitializePCMInternal();
   InitializePDP();

hal/src/main/native/athena/HALInitializer.h

@@ -1,5 +1,5 @@
 /*----------------------------------------------------------------------------*/
-/* Copyright (c) 2017-2018 FIRST. All Rights Reserved.                        */
+/* Copyright (c) 2017-2019 FIRST. All Rights Reserved.                        */
 /* Open Source Software - may be modified and shared by FRC teams. The code   */
 /* must be accompanied by the FIRST BSD license file in the root directory of */
 /* the project.                                                               */
@@ -38,6 +38,7 @@ extern void InitializeFRCDriverStation();
 extern void InitializeHAL();
 extern void InitializeI2C();
 extern void InitialzeInterrupts();
+extern void InitializeMain();
 extern void InitializeNotifier();
 extern void InitializePCMInternal();
 extern void InitializePDP();

hal/src/main/native/cpp/Main.cpp

@@ -0,0 +1,64 @@
+/*----------------------------------------------------------------------------*/
+/* Copyright (c) 2019 FIRST. All Rights Reserved.                             */
+/* Open Source Software - may be modified and shared by FRC teams. The code   */
+/* must be accompanied by the FIRST BSD license file in the root directory of */
+/* the project.                                                               */
+/*----------------------------------------------------------------------------*/
+
+#include "hal/Main.h"
+
+#include <wpi/condition_variable.h>
+#include <wpi/mutex.h>
+
+static void DefaultMain(void*);
+static void DefaultExit(void*);
+
+static bool gHasMain = false;
+static void* gMainParam = nullptr;
+static void (*gMainFunc)(void*) = DefaultMain;
+static void (*gExitFunc)(void*) = DefaultExit;
+static bool gExited = false;
+struct MainObj {
+  wpi::mutex gExitMutex;
+  wpi::condition_variable gExitCv;
+};
+
+static MainObj* mainObj;
+
+static void DefaultMain(void*) {
+  std::unique_lock lock{mainObj->gExitMutex};
+  mainObj->gExitCv.wait(lock, [] { return gExited; });
+}
+
+static void DefaultExit(void*) {
+  std::lock_guard lock{mainObj->gExitMutex};
+  gExited = true;
+  mainObj->gExitCv.notify_all();
+}
+
+namespace hal {
+namespace init {
+void InitializeMain() {
+  static MainObj mO;
+  mainObj = &mO;
+}
+}  // namespace init
+}  // namespace hal
+
+extern "C" {
+
+void HAL_SetMain(void* param, void (*mainFunc)(void*),
+                 void (*exitFunc)(void*)) {
+  gHasMain = true;
+  gMainParam = param;
+  gMainFunc = mainFunc;
+  gExitFunc = exitFunc;
+}
+
+HAL_Bool HAL_HasMain(void) { return gHasMain; }
+
+void HAL_RunMain(void) { gMainFunc(gMainParam); }
+
+void HAL_ExitMain(void) { gExitFunc(gMainParam); }
+
+}  // extern "C"

hal/src/main/native/cpp/jni/HAL.cpp

@@ -17,6 +17,7 @@
 #include "HALUtil.h"
 #include "edu_wpi_first_hal_HAL.h"
 #include "hal/DriverStation.h"
+#include "hal/Main.h"
 
 using namespace frc;
 using namespace wpi::java;
@@ -35,6 +36,42 @@ Java_edu_wpi_first_hal_HAL_initialize
   return HAL_Initialize(timeout, mode);
 }
 
+/*
+ * Class:     edu_wpi_first_hal_HAL
+ * Method:    hasMain
+ * Signature: ()Z
+ */
+JNIEXPORT jboolean JNICALL
+Java_edu_wpi_first_hal_HAL_hasMain
+  (JNIEnv*, jclass)
+{
+  return HAL_HasMain();
+}
+
+/*
+ * Class:     edu_wpi_first_hal_HAL
+ * Method:    runMain
+ * Signature: ()V
+ */
+JNIEXPORT void JNICALL
+Java_edu_wpi_first_hal_HAL_runMain
+  (JNIEnv*, jclass)
+{
+  HAL_RunMain();
+}
+
+/*
+ * Class:     edu_wpi_first_hal_HAL
+ * Method:    exitMain
+ * Signature: ()V
+ */
+JNIEXPORT void JNICALL
+Java_edu_wpi_first_hal_HAL_exitMain
+  (JNIEnv*, jclass)
+{
+  HAL_ExitMain();
+}
+
 /*
  * Class:     edu_wpi_first_hal_HAL
  * Method:    observeUserProgramStarting

hal/src/main/native/include/hal/HAL.h

@@ -27,6 +27,7 @@
 #include "hal/HALBase.h"
 #include "hal/I2C.h"
 #include "hal/Interrupts.h"
+#include "hal/Main.h"
 #include "hal/Notifier.h"
 #include "hal/PDP.h"
 #include "hal/PWM.h"

hal/src/main/native/include/hal/Main.h

@@ -0,0 +1,67 @@
+/*----------------------------------------------------------------------------*/
+/* Copyright (c) 2019 FIRST. All Rights Reserved.                             */
+/* Open Source Software - may be modified and shared by FRC teams. The code   */
+/* must be accompanied by the FIRST BSD license file in the root directory of */
+/* the project.                                                               */
+/*----------------------------------------------------------------------------*/
+
+#pragma once
+
+#include <stdint.h>
+
+#include "hal/Types.h"
+
+/**
+ * @defgroup hal_relay Main loop functions
+ * @ingroup hal_capi
+ * @{
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Sets up the system to run the provided main loop in the main thread (e.g.
+ * the thread in which main() starts execution) and run the robot code in a
+ * separate thread.
+ *
+ * Normally the robot code runs in the main thread, but some GUI systems
+ * require the GUI be run in the main thread.
+ *
+ * To be effective, this function must be called before the robot code starts
+ * the main loop (e.g. by frc::StartRobot()).
+ *
+ * @param param parameter data to pass to mainFunc and exitFunc
+ * @param mainFunc the function to be run when HAL_RunMain() is called.
+ * @param exitFunc the function to be run when HAL_ExitMain() is called.
+ */
+void HAL_SetMain(void* param, void (*mainFunc)(void*), void (*exitFunc)(void*));
+
+/**
+ * Returns true if HAL_SetMain() has been called.
+ *
+ * @return True if HAL_SetMain() has been called, false otherwise.
+ */
+HAL_Bool HAL_HasMain(void);
+
+/**
+ * Runs the main function provided to HAL_SetMain().
+ *
+ * If HAL_SetMain() has not been called, simply sleeps until HAL_ExitMain()
+ * is called.
+ */
+void HAL_RunMain(void);
+
+/**
+ * Causes HAL_RunMain() to exit.
+ *
+ * If HAL_SetMain() has been called, this calls the exit function provided
+ * to that function.
+ */
+void HAL_ExitMain(void);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+/** @} */

hal/src/main/native/sim/HAL.cpp

@@ -60,6 +60,7 @@ void InitializeHAL() {
   InitializeExtensions();
   InitializeI2C();
   InitializeInterrupts();
+  InitializeMain();
   InitializeMockHooks();
   InitializeNotifier();
   InitializePDP();

hal/src/main/native/sim/HALInitializer.h

@@ -1,5 +1,5 @@
 /*----------------------------------------------------------------------------*/
-/* Copyright (c) 2017-2018 FIRST. All Rights Reserved.                        */
+/* Copyright (c) 2017-2019 FIRST. All Rights Reserved.                        */
 /* Open Source Software - may be modified and shared by FRC teams. The code   */
 /* must be accompanied by the FIRST BSD license file in the root directory of */
 /* the project.                                                               */
@@ -55,6 +55,7 @@ extern void InitializeExtensions();
 extern void InitializeHAL();
 extern void InitializeI2C();
 extern void InitializeInterrupts();
+extern void InitializeMain();
 extern void InitializeMockHooks();
 extern void InitializeNotifier();
 extern void InitializePDP();