\hypertarget{class_qore_1_1_thread_1_1_condition}{}\doxysection{Qore\+::Thread\+::Condition Class Reference} \label{class_qore_1_1_thread_1_1_condition}\index{Qore::Thread::Condition@{Qore::Thread::Condition}} The \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} class can be used For blocking a thread until a condition becomes \mbox{\hyperlink{basic_data_types_True}{True}}. \doxysubsection*{Public Member Functions} \begin{DoxyCompactItemize} \item nothing \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a0bf35f288c7fe337d6c23966587cf74e}{broadcast}} () \begin{DoxyCompactList}\small\item\em Signals all threads blocked on this \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object to wake up. \end{DoxyCompactList}\item \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_aa2884ef6c32a55b3928b8d363639800d}{constructor}} () \begin{DoxyCompactList}\small\item\em Creates the \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object. \end{DoxyCompactList}\item \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a3af34f32349da258b5bb35bca14b932c}{copy}} () \begin{DoxyCompactList}\small\item\em Creates a new \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object, not based on the original. \end{DoxyCompactList}\item nothing \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a639be7dc86bf755e1ee31cd3eefff4d5}{signal}} () \begin{DoxyCompactList}\small\item\em Signals a single blocked thread to wake up. \end{DoxyCompactList}\item \mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a8f29b21d4146f40315e25d3bbf840196}{wait}} (\mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} lock, timeout timeout\+\_\+ms=0) \begin{DoxyCompactList}\small\item\em Blocks a thread until signaled; accepts an optional timeout value. \end{DoxyCompactList}\item \mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a9344dce8d42904abaecb8136cc171ee5}{wait\+\_\+count}} (\mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} lock) \begin{DoxyCompactList}\small\item\em Returns the number of threads currently blocked on this object using the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} passed. \end{DoxyCompactList}\end{DoxyCompactItemize} \doxysubsection{Detailed Description} The \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} class can be used For blocking a thread until a condition becomes \mbox{\hyperlink{basic_data_types_True}{True}}. \begin{DoxyParagraph}{Restrictions\+:} \mbox{\hyperlink{group__parse__options_gade963e1fbbd1f5b2c777df7221512a1b}{Qore\+::\+PO\+\_\+\+NO\+\_\+\+THREAD\+\_\+\+CLASSES}} \end{DoxyParagraph} \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} objects, when used along with an \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object (such as \mbox{\hyperlink{class_qore_1_1_thread_1_1_r_w_lock}{RWLock}} and \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} objects), allow Qore threads to sleep until a certain condition becomes \mbox{\hyperlink{basic_data_types_True}{True}}. \begin{DoxyNote}{Note} This class is not available with the \mbox{\hyperlink{group__parse__options_gade963e1fbbd1f5b2c777df7221512a1b}{PO\+\_\+\+NO\+\_\+\+THREAD\+\_\+\+CLASSES}} parse option. \end{DoxyNote} \doxysubsection{Member Function Documentation} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_condition_a0bf35f288c7fe337d6c23966587cf74e}\label{class_qore_1_1_thread_1_1_condition_a0bf35f288c7fe337d6c23966587cf74e}} \index{Qore::Thread::Condition@{Qore::Thread::Condition}!broadcast@{broadcast}} \index{broadcast@{broadcast}!Qore::Thread::Condition@{Qore::Thread::Condition}} \doxysubsubsection{\texorpdfstring{broadcast()}{broadcast()}} {\footnotesize\ttfamily nothing Qore\+::\+Thread\+::\+Condition\+::broadcast (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Signals all threads blocked on this \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object to wake up. Normally this method call will be made while the same \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object used for \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a8f29b21d4146f40315e25d3bbf840196}{Condition\+::wait()}} calls is locked. Then, when the thread calling this method unlocks the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object, the thread(s) woken up by this call can continue executing. \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{m.lock();} \DoxyCodeLine{cond.broadcast();} \DoxyCodeLine{m.unlock();} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyExceptions}{Exceptions} {\em CONDITION-\/\+BROADCAST-\/\+ERROR} & This exception should never be thrown -\/ it indicates a low-\/level error in executing the method \\ \hline \end{DoxyExceptions} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_condition_aa2884ef6c32a55b3928b8d363639800d}\label{class_qore_1_1_thread_1_1_condition_aa2884ef6c32a55b3928b8d363639800d}} \index{Qore::Thread::Condition@{Qore::Thread::Condition}!constructor@{constructor}} \index{constructor@{constructor}!Qore::Thread::Condition@{Qore::Thread::Condition}} \doxysubsubsection{\texorpdfstring{constructor()}{constructor()}} {\footnotesize\ttfamily Qore\+::\+Thread\+::\+Condition\+::constructor (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Creates the \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object. \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{Condition cond();} \end{DoxyCode} \end{DoxyParagraph} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_condition_a3af34f32349da258b5bb35bca14b932c}\label{class_qore_1_1_thread_1_1_condition_a3af34f32349da258b5bb35bca14b932c}} \index{Qore::Thread::Condition@{Qore::Thread::Condition}!copy@{copy}} \index{copy@{copy}!Qore::Thread::Condition@{Qore::Thread::Condition}} \doxysubsubsection{\texorpdfstring{copy()}{copy()}} {\footnotesize\ttfamily Qore\+::\+Thread\+::\+Condition\+::copy (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Creates a new \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object, not based on the original. \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{Condition new\_cond = cond.copy();} \end{DoxyCode} \end{DoxyParagraph} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_condition_a639be7dc86bf755e1ee31cd3eefff4d5}\label{class_qore_1_1_thread_1_1_condition_a639be7dc86bf755e1ee31cd3eefff4d5}} \index{Qore::Thread::Condition@{Qore::Thread::Condition}!signal@{signal}} \index{signal@{signal}!Qore::Thread::Condition@{Qore::Thread::Condition}} \doxysubsubsection{\texorpdfstring{signal()}{signal()}} {\footnotesize\ttfamily nothing Qore\+::\+Thread\+::\+Condition\+::signal (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Signals a single blocked thread to wake up. Normally this method call will be made while the same \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object used for \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a8f29b21d4146f40315e25d3bbf840196}{Condition\+::wait()}} calls is locked. Then, when the thread calling this method unlocks the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object, the thread woken up by this call can continue executing. \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{m.lock();} \DoxyCodeLine{cond.signal();} \DoxyCodeLine{m.unlock();} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyExceptions}{Exceptions} {\em CONDITION-\/\+SIGNAL-\/\+ERROR} & This exception should never be thrown -\/ it indicates a low-\/level error in executing the method \\ \hline \end{DoxyExceptions} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_condition_a8f29b21d4146f40315e25d3bbf840196}\label{class_qore_1_1_thread_1_1_condition_a8f29b21d4146f40315e25d3bbf840196}} \index{Qore::Thread::Condition@{Qore::Thread::Condition}!wait@{wait}} \index{wait@{wait}!Qore::Thread::Condition@{Qore::Thread::Condition}} \doxysubsubsection{\texorpdfstring{wait()}{wait()}} {\footnotesize\ttfamily \mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} Qore\+::\+Thread\+::\+Condition\+::wait (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}}}]{lock, }\item[{timeout}]{timeout\+\_\+ms = {\ttfamily 0} }\end{DoxyParamCaption})} Blocks a thread until signaled; accepts an optional timeout value. Must be called with an \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} argument, and the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} must be locked before the call. This method will atomically unlock the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object and wait on this \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object to be woken up with a \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a639be7dc86bf755e1ee31cd3eefff4d5}{Condition\+::signal()}} or \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a0bf35f288c7fe337d6c23966587cf74e}{Condition\+::broadcast()}} method call in another thread. At this point, the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} will be reacquired with the same state as it was acquired previously before control returns to the blocked thread. The wait condition should always be tested again when the thread is unblocked. \begin{DoxyParams}{Parameters} {\em lock} & the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object to use for synchronization on this \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object. The \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} must be locked before calling this method \\ \hline {\em timeout\+\_\+ms} & a \mbox{\hyperlink{data_type_declarations_timeout_type}{timeout}} value to wait for the condition to be triggered; integers are interpreted as milliseconds; \mbox{\hyperlink{basic_data_types_relative_dates}{relative date/time values}} are interpreted literally (with a resolution of milliseconds). Timeout values $<$= 0 mean do not time out. If a timeout value $>$ 0 is given and the call times out, the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} will also be acquired when the \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition_a8f29b21d4146f40315e25d3bbf840196}{Condition\+::wait()}} call returns and {\ttfamily ETIMEDOUT} will be returned.\\ \hline \end{DoxyParams} \begin{DoxyReturn}{Returns} 0 for success, {\ttfamily ETIMEDOUT} if a timeout has occurred \end{DoxyReturn} \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{m.lock();} \DoxyCodeLine{on\_exit m.unlock();} \DoxyCodeLine{\textcolor{keywordflow}{while} (some\_value > 0) \{} \DoxyCodeLine{ cond.wait(m);} \DoxyCodeLine{\}} \DoxyCodeLine{\mbox{\hyperlink{group__string__functions_ga32070517a9f8a70a32ef48f83a6f128e}{printf}}(\textcolor{stringliteral}{"{}finally some\_value is 0\(\backslash\)n"{}});} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyExceptions}{Exceptions} {\em CONDITION-\/\+WAIT-\/\+ERROR} & This exception should never be thrown -\/ it indicates a low-\/level error in executing the method \\ \hline \end{DoxyExceptions} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_condition_a9344dce8d42904abaecb8136cc171ee5}\label{class_qore_1_1_thread_1_1_condition_a9344dce8d42904abaecb8136cc171ee5}} \index{Qore::Thread::Condition@{Qore::Thread::Condition}!wait\_count@{wait\_count}} \index{wait\_count@{wait\_count}!Qore::Thread::Condition@{Qore::Thread::Condition}} \doxysubsubsection{\texorpdfstring{wait\_count()}{wait\_count()}} {\footnotesize\ttfamily \mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} Qore\+::\+Thread\+::\+Condition\+::wait\+\_\+count (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}}}]{lock }\end{DoxyParamCaption})} Returns the number of threads currently blocked on this object using the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} passed. \begin{DoxyParams}{Parameters} {\em lock} & the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object to check for blocked threads on this \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} object; the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} can be in any state (locked or unlocked) for this call (does not necessarily have to be locked).\\ \hline \end{DoxyParams} \begin{DoxyReturn}{Returns} The number of threads currently blocked on this object using the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}} object passed \end{DoxyReturn} \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{\mbox{\hyperlink{group__string__functions_ga32070517a9f8a70a32ef48f83a6f128e}{printf}}(\textcolor{stringliteral}{"{}\%d thread(s) waiting on the Condition\(\backslash\)n"{}}, cond.wait\_count(m));} \end{DoxyCode} \end{DoxyParagraph}