fixed comments in Error* stuff
diff --git a/aos/externals/WPILib/WPILib/Error.cpp b/aos/externals/WPILib/WPILib/Error.cpp
index c610ad7..6c1af7c 100644
--- a/aos/externals/WPILib/WPILib/Error.cpp
+++ b/aos/externals/WPILib/WPILib/Error.cpp
@@ -29,7 +29,8 @@
* Clones another error into this if this is currently clear. If not, does
* nothing.
* This is necessary because just using "if (!IsClear()) Clone(error)" has a
- * race condition.
+ * race condition which this method does not.
+ * Cloning 2 errors into each other at the same time can lead to deadlocks!
*/
void Error::CloneIfClear(const Error &error) {
Synchronized sync(m_semaphore);
@@ -40,6 +41,7 @@
/**
* Clones another error into this object.
+ * Cloning 2 errors into each other at the same time can lead to deadlocks!
*/
void Error::Clone(const Error &error) {
Synchronized sync(m_semaphore);
diff --git a/aos/externals/WPILib/WPILib/Error.h b/aos/externals/WPILib/WPILib/Error.h
index 545b23b..9636262 100644
--- a/aos/externals/WPILib/WPILib/Error.h
+++ b/aos/externals/WPILib/WPILib/Error.h
@@ -18,7 +18,7 @@
/**
* Represents an error or warning.
*
- * All methods that can change instance variables are protected by a lock so
+ * All methods that can change instance data are protected by a lock so
* that it is safe to call any methods from multiple tasks at the same time.
*/
class Error
@@ -38,7 +38,8 @@
bool IsClear() const;
Code GetCode() const;
- // Have to return by value to avoid race conditions using the result.
+ // Have to return by value to avoid race conditions using the result for all
+ // of these methods.
std::string GetMessage() const;
std::string GetFilename() const;
std::string GetFunction() const;
@@ -66,6 +67,9 @@
UINT32 m_lineNumber;
const ErrorBase* m_originatingObject;
double m_timestamp;
+ // Used for protecting all modifications to instance data.
+ // This means that all non-const methods should lock this for (at least most)
+ // of their implementations!
ReentrantSemaphore m_semaphore;
static bool m_stackTraceEnabled;
diff --git a/aos/externals/WPILib/WPILib/ErrorBase.cpp b/aos/externals/WPILib/WPILib/ErrorBase.cpp
index 6c89070..838c0ee 100644
--- a/aos/externals/WPILib/WPILib/ErrorBase.cpp
+++ b/aos/externals/WPILib/WPILib/ErrorBase.cpp
@@ -26,8 +26,8 @@
{}
/**
- * @brief Retrieve the current error.
- * Get the current error information associated with this sensor.
+ * @brief Retrieve the error associated this object.
+ * Get the error information associated with this sensor.
*/
Error& ErrorBase::GetError() const
{
@@ -45,7 +45,8 @@
/**
* @brief Set error information associated with a C library call that set an
* error to the "errno" "global variable" (it's really a macro that calls a
- * function so that it's thread safe).
+ * function under VxWorks so that it's thread safe).
+ * Will still set an error even if errno is 0.
*
* @param contextMessage A custom message from the code that set the error.
* @param filename Filename of the error source
@@ -82,6 +83,7 @@
/**
* @brief Set the current error information associated from the nivision Imaq API.
+ * Does nothing of success is > 0.
*
* @param success The return from the function
* @param contextMessage A custom message from the code that set the error.
@@ -104,7 +106,8 @@
}
/**
- * @brief Set the current error information associated with this sensor.
+ * @brief Set the current error information associated with this object.
+ * Does nothing if code is 0.
*
* @param code The error code
* @param contextMessage A custom message from the code that set the error.
@@ -125,7 +128,7 @@
}
/**
- * @brief Set the current error information associated with this sensor.
+ * @brief Set the current error information associated with this object.
*
* @param errorMessage The error message from WPIErrors.h
* @param contextMessage A custom message from the code that set the error.
@@ -160,6 +163,16 @@
return m_error.GetCode() < 0;
}
+/**
+ * @brief Set the current global error information.
+ * Does nothing if code is 0.
+ *
+ * @param code The error code
+ * @param contextMessage A custom message from the code that set the error.
+ * @param filename Filename of the error source
+ * @param function Function of the error source
+ * @param lineNumber Line number of the error source
+ */
void ErrorBase::SetGlobalError(Error::Code code, const char *contextMessage,
const char* filename, const char* function, UINT32 lineNumber)
{
@@ -167,6 +180,15 @@
_globalError.Set(code, contextMessage, filename, function, lineNumber, NULL);
}
+/**
+ * @brief Set the current global error information.
+ *
+ * @param errorMessage The error message from WPIErrors.h
+ * @param contextMessage A custom message from the code that set the error.
+ * @param filename Filename of the error source
+ * @param function Function of the error source
+ * @param lineNumber Line number of the error source
+ */
void ErrorBase::SetGlobalWPIError(const char *errorMessage, const char *contextMessage,
const char* filename, const char* function, UINT32 lineNumber)
{
@@ -177,7 +199,7 @@
}
/**
- * Retrieve the current global error.
+ * Retrieve the global error.
*/
const Error& ErrorBase::GetGlobalError()
{
diff --git a/aos/externals/WPILib/WPILib/ErrorBase.h b/aos/externals/WPILib/WPILib/ErrorBase.h
index afa2f4c..9d032cb 100644
--- a/aos/externals/WPILib/WPILib/ErrorBase.h
+++ b/aos/externals/WPILib/WPILib/ErrorBase.h
@@ -52,8 +52,8 @@
*
* BE AWARE: This does include a mutable instance variable! This means that even
* if you make an object const it's not really. However, all modification to
- * that instance variable is protected by a semaphore, so it does not create
- * more thread safety issues.
+ * that instance variable is protected by a semaphore, so it does not create any
+ * thread safety issues.
*
* All of the Set*Error methods will update the global error if there is nothing
* there already.
@@ -86,7 +86,8 @@
// This mutable is safe because Error guarantees that all modifications are
// protected with an internal lock.
mutable Error m_error;
- // TODO: Replace globalError with a global list of all errors.
+ // TODO: Replace globalError with a global list of all errors, but make sure
+ // that it's thread safe.
static Error _globalError;
private: