[Libreoffice-commits] core.git: include/osl
Chris Sherlock
chris.sherlock79 at gmail.com
Mon May 29 12:45:42 UTC 2017
include/osl/conditn.h | 35 +++++++++++++----
include/osl/conditn.hxx | 95 +++++++++++++++++++++++++++++-------------------
2 files changed, 84 insertions(+), 46 deletions(-)
New commits:
commit bd4aa1e09aa9fcedc381460e44bfc49a9f933786
Author: Chris Sherlock <chris.sherlock79 at gmail.com>
Date: Sun May 28 14:52:48 2017 +1000
osl: conditin.h and conditin.hxx doxygen updates
Change-Id: Ibdfa34d2b3b93ba0b5d5211dd4f843d849375e64
Reviewed-on: https://gerrit.libreoffice.org/38100
Tested-by: Jenkins <ci at libreoffice.org>
Reviewed-by: Chris Sherlock <chris.sherlock79 at gmail.com>
diff --git a/include/osl/conditn.h b/include/osl/conditn.h
index 26d2cb103d62..a087f3504a49 100644
--- a/include/osl/conditn.h
+++ b/include/osl/conditn.h
@@ -32,9 +32,9 @@ extern "C" {
typedef void* oslCondition;
typedef enum {
- osl_cond_result_ok, /* successful completion */
- osl_cond_result_error, /* error occurred, check osl_getLastSocketError() for details */
- osl_cond_result_timeout, /* blocking operation timed out */
+ osl_cond_result_ok, /*<! Successful completion. */
+ osl_cond_result_error, /*<! Error occurred. @see osl_getLastSocketError() */
+ osl_cond_result_timeout, /*<! Blocking operation timed out. */
osl_cond_result_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslConditionResult;
@@ -44,38 +44,55 @@ typedef enum {
for a more robust and helpful condition.
The condition is in the reset-state.
- @retval 0 if condition could not be created.
+
+ @relates Condition
+
+ @retval osl_cond_result_error Condition could not be created.
*/
SAL_DLLPUBLIC oslCondition SAL_CALL osl_createCondition(void);
/** Free the memory used by the condition.
+
+ @relates Condition
+
@param Condition the condition handle.
*/
SAL_DLLPUBLIC void SAL_CALL osl_destroyCondition(oslCondition Condition);
/** Sets condition to True => wait() will not block, check() returns True.
- NOTE: ALL threads waiting on this condition are unblocked!
+
+ @attention @em all threads waiting on this condition are unblocked!
+
+ @relates Condition
+
@param Condition handle to a created condition.
@retval False if system-call failed.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setCondition(oslCondition Condition);
/** Sets condition to False => wait() will block, check() returns False
+
+ @relates Condition
+
@param Condition handle to a created condition.
@retval False if system-call failed.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_resetCondition(oslCondition Condition);
-/** Blocks if condition is not set
- If condition has been destroyed prematurely, wait() will
- return with False.
+/** Blocks if condition is not set.
+
+ @relates Condition
+
@param Condition handle to a created condition.
@param pTimeout Timeout value or NULL for infinite waiting
- @return False if system-call failed.
+ @retval False Condition has been destroyed prematurely or system call has failed.
*/
SAL_DLLPUBLIC oslConditionResult SAL_CALL osl_waitCondition(oslCondition Condition, const TimeValue* pTimeout);
/** Queries the state of the condition without blocking.
+
+ @relates Condition
+
@param Condition handle to a created condition.
@retval True condition is set
@retval False condition is not set
diff --git a/include/osl/conditn.hxx b/include/osl/conditn.hxx
index 07d697948077..ffc7cc6b5c82 100644
--- a/include/osl/conditn.hxx
+++ b/include/osl/conditn.hxx
@@ -20,12 +20,10 @@
#ifndef INCLUDED_OSL_CONDITN_HXX
#define INCLUDED_OSL_CONDITN_HXX
-#include <sal/config.h>
-
#include <cstddef>
+#include <sal/config.h>
#include <osl/time.h>
-
#include <osl/conditn.h>
#if defined(MACOSX) && defined(__ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES)
@@ -36,63 +34,78 @@
namespace osl
{
- /**
- * A deprecated condition.
- *
- * @deprecated use C++11's std::condition_variable instead
- * for a more robust and helpful condition.
- *
- * Warning: the Condition abstraction is inadequate for any
- * situation where there may be multiple threads setting,
- * waiting, and resetting the same condition. It can only be
- * used to synchronise interactions between two threads
- * cf. lost wakeups in:
- * http://www.cs.wustl.edu/~schmidt/win32-cv-1.html
- */
+ /** Condition variable
+
+ A condition variable is essentially an object that is initially
+ cleared which a thread waits on until it is "set". It allows a
+ thread to synchronize execution by allowing other threads to wait
+ for the condition to change before that thread then continues
+ execution.
+
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
+
+ @attention Warning: the Condition abstraction is inadequate for
+ any situation where there may be multiple threads setting,
+ waiting, and resetting the same condition. It can only be
+ used to synchronise interactions between two threads
+ cf. lost wakeups in http://www.cs.wustl.edu/~schmidt/win32-cv-1.html
+ */
class Condition
{
public:
-
enum Result
{
- result_ok = osl_cond_result_ok,
- result_error = osl_cond_result_error,
- result_timeout = osl_cond_result_timeout
+ result_ok = osl_cond_result_ok, /*!< Succesful completion. */
+ result_error = osl_cond_result_error, /*!< Error occurred. @see osl_getLastSocketError() */
+ result_timeout = osl_cond_result_timeout /*!< Blocking operation timed out. */
};
- /**
- * Create a condition.
- *
- * @deprecated use C++11's std::condition_variable instead
- * for a more robust and helpful condition.
- */
+ /** Create a condition.
+
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
+ */
Condition()
{
condition = osl_createCondition();
}
- /* Release the OS-structures and free condition data-structure.
- */
+ /** Release the OS-structures and free condition data-structure.
+
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
+ */
~Condition()
{
osl_destroyCondition(condition);
}
- /* Release all waiting threads, check returns true.
- */
+ /** Release all waiting threads, check returns true.
+
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
+ */
void set()
{
osl_setCondition(condition);
}
- /* Reset condition to false: wait() will block, check() returns false.
- */
+ /** Reset condition to false: wait() will block, check() returns
+ false.
+
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
+ */
void reset() {
osl_resetCondition(condition);
}
/** Blocks the calling thread until condition is set.
- */
+
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
+ */
Result wait(const TimeValue *pTimeout = NULL)
{
return (Result) osl_waitCondition(condition, pTimeout);
@@ -103,7 +116,10 @@ namespace osl
#endif
/** Checks if the condition is set without blocking.
- */
+
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
+ */
bool check()
{
return osl_checkCondition(condition);
@@ -115,18 +131,23 @@ namespace osl
/** The underlying oslCondition has no reference count.
- Since the underlying oslCondition is not a reference counted object, copy
- constructed Condition may work on an already destructed oslCondition object.
+ Since the underlying oslCondition is not a reference counted
+ object, copy constructed Condition may work on an already
+ destructed oslCondition object.
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
*/
Condition(const Condition&) SAL_DELETED_FUNCTION;
/** This assignment operator is deleted for the same reason as
the copy constructor.
+
+ @deprecated use C++11's std::condition_variable instead
+ for a more robust and helpful condition.
*/
Condition& operator= (const Condition&) SAL_DELETED_FUNCTION;
};
-
}
#endif // INCLUDED_OSL_CONDITN_HXX
More information about the Libreoffice-commits
mailing list