\hypertarget{class_qore_1_1_thread_1_1_mutex}{}\doxysection{Qore\+::Thread\+::Mutex Class Reference} \label{class_qore_1_1_thread_1_1_mutex}\index{Qore::Thread::Mutex@{Qore::Thread::Mutex}} A class providing an implementation for a simple thread lock. Inheritance diagram for Qore\+::Thread\+::Mutex\+: \nopagebreak \begin{figure}[H] \begin{center} \leavevmode \includegraphics[width=258pt]{class_qore_1_1_thread_1_1_mutex__inherit__graph} \end{center} \end{figure} \doxysubsection*{Public Member Functions} \begin{DoxyCompactItemize} \item \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_ac840b8963339af09900272734751699c}{constructor}} () \begin{DoxyCompactList}\small\item\em Creates the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object. \end{DoxyCompactList}\item \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_aab5cdf5a49a4fed57165ce3afa749e29}{copy}} () \begin{DoxyCompactList}\small\item\em Creates a new \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object, not based on the original. \end{DoxyCompactList}\item \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a1a210a99ba91b43130d6b9ef4c7301c4}{destructor}} () \begin{DoxyCompactList}\small\item\em Destroys the object. \end{DoxyCompactList}\item nothing \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a0bb3432456ccdf0cfb1523429b5b4141}{lock}} () \begin{DoxyCompactList}\small\item\em Locks the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object; blocks if the lock is already held. \end{DoxyCompactList}\item \mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a22c7752a61e7ae1e1c1e87a20b8dd0f4}{lock}} (timeout timeout\+\_\+ms) \begin{DoxyCompactList}\small\item\em Locks the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object; blocks if the lock is already held. \end{DoxyCompactList}\item \mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_abcc3818211d37882c0549bfcbe7c487b}{trylock}} () \begin{DoxyCompactList}\small\item\em Acquires the lock only if it is not already held; returns 0 for success (lock acquired) or -\/1 if the call would block. \end{DoxyCompactList}\item nothing \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a23adbdd9cd3ffe17b1cbc700716aec5c}{unlock}} () \begin{DoxyCompactList}\small\item\em Unlocks the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object; wakes up one thread if any threads are blocked on this lock. \end{DoxyCompactList}\end{DoxyCompactItemize} \doxysubsection{Detailed Description} A class providing an implementation for a simple thread lock. \begin{DoxyParagraph}{Restrictions\+:} \mbox{\hyperlink{group__parse__options_gade963e1fbbd1f5b2c777df7221512a1b}{Qore\+::\+PO\+\_\+\+NO\+\_\+\+THREAD\+\_\+\+CLASSES}} \end{DoxyParagraph} \begin{DoxyParagraph}{Overview} This class inherits \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}}, so it can be used by \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} objects.~\newline ~\newline The \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} class implements a mutual-\/exclusion lock for thread locking. Like all Qore thread primitives, objects of this class participate in deadlock detection and throw exceptions when threading errors occur (ex\+: unlocking a \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object locked by another thread, etc). See individual methods for more information on exceptions thrown.~\newline ~\newline See the \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_lock}{Auto\+Lock}} class for a class that assists in exception-\/safe \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} locking.~\newline ~\newline Additionally, the \mbox{\hyperlink{statements_on_exit}{on\+\_\+exit statement}} can provide exception-\/safe unlocking at the lexical block level for \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} objects as in the following example\+: \begin{DoxyCode}{0} \DoxyCodeLine{\{} \DoxyCodeLine{ m.lock();} \DoxyCodeLine{ on\_exit} \DoxyCodeLine{ m.unlock();} \DoxyCodeLine{} \DoxyCodeLine{ \textcolor{comment}{\# ... when this block exits the lock will be released, even in the}} \DoxyCodeLine{ \textcolor{comment}{\# case of return statements or exceptions}} \DoxyCodeLine{\}} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyParagraph}{Thread Resource Handling} The \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} class manages the lock as a \mbox{\hyperlink{threading_thread_resources}{thread resource}}; if the lock is not released when the thread exits (or when \mbox{\hyperlink{group__threading__functions_ga421dca39ccb55b191d5d09fd98c2075a}{Qore\+::throw\+\_\+thread\+\_\+resource\+\_\+exceptions()}} or \mbox{\hyperlink{group__threading__functions_ga4e62409b8a1b414276d033267e7299e4}{Qore\+::throw\+\_\+thread\+\_\+resource\+\_\+exceptions\+\_\+to\+\_\+mark()}} is called), the lock is released automatically and a {\ttfamily LOCK-\/\+ERROR} exception is thrown describing the situation.~\newline ~\newline Being an builtin class, the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} class does not inherit \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_thread_resource}{Abstract\+Thread\+Resource}} explicitly as a part of the exported API, and the internal \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_thread_resource_a0431f7384991eaf6900ee3a952b57f87}{Abstract\+Thread\+Resource\+::cleanup()}} method cannot be overridden or suppressed. \end{DoxyParagraph} \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_mutex_ac840b8963339af09900272734751699c}\label{class_qore_1_1_thread_1_1_mutex_ac840b8963339af09900272734751699c}} \index{Qore::Thread::Mutex@{Qore::Thread::Mutex}!constructor@{constructor}} \index{constructor@{constructor}!Qore::Thread::Mutex@{Qore::Thread::Mutex}} \doxysubsubsection{\texorpdfstring{constructor()}{constructor()}} {\footnotesize\ttfamily Qore\+::\+Thread\+::\+Mutex\+::constructor (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Creates the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object. \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{Mutex mutex();} \end{DoxyCode} \end{DoxyParagraph} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_mutex_aab5cdf5a49a4fed57165ce3afa749e29}\label{class_qore_1_1_thread_1_1_mutex_aab5cdf5a49a4fed57165ce3afa749e29}} \index{Qore::Thread::Mutex@{Qore::Thread::Mutex}!copy@{copy}} \index{copy@{copy}!Qore::Thread::Mutex@{Qore::Thread::Mutex}} \doxysubsubsection{\texorpdfstring{copy()}{copy()}} {\footnotesize\ttfamily Qore\+::\+Thread\+::\+Mutex\+::copy (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Creates a new \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object, not based on the original. \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{Mutex nm = m.copy();} \end{DoxyCode} \end{DoxyParagraph} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_mutex_a1a210a99ba91b43130d6b9ef4c7301c4}\label{class_qore_1_1_thread_1_1_mutex_a1a210a99ba91b43130d6b9ef4c7301c4}} \index{Qore::Thread::Mutex@{Qore::Thread::Mutex}!destructor@{destructor}} \index{destructor@{destructor}!Qore::Thread::Mutex@{Qore::Thread::Mutex}} \doxysubsubsection{\texorpdfstring{destructor()}{destructor()}} {\footnotesize\ttfamily Qore\+::\+Thread\+::\+Mutex\+::destructor (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Destroys the object. Note that it is a programming error to delete this object while other threads are blocked on it; in this case an exception is thrown in the deleting thread, and in each thread blocked on this object when it is deleted. \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{delete mutex;} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyExceptions}{Exceptions} {\em LOCK-\/\+ERROR} & Object deleted while other threads blocked on it \\ \hline \end{DoxyExceptions} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_mutex_a0bb3432456ccdf0cfb1523429b5b4141}\label{class_qore_1_1_thread_1_1_mutex_a0bb3432456ccdf0cfb1523429b5b4141}} \index{Qore::Thread::Mutex@{Qore::Thread::Mutex}!lock@{lock}} \index{lock@{lock}!Qore::Thread::Mutex@{Qore::Thread::Mutex}} \doxysubsubsection{\texorpdfstring{lock()}{lock()}\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}} {\footnotesize\ttfamily nothing Qore\+::\+Thread\+::\+Mutex\+::lock (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Locks the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object; blocks if the lock is already held. To release the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}}, use \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a23adbdd9cd3ffe17b1cbc700716aec5c}{Mutex\+::unlock()}} \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{mutex.lock();} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyExceptions}{Exceptions} {\em LOCK-\/\+ERROR} & lock called twice in the same thread, object deleted in another thread, etc \\ \hline {\em THREAD-\/\+DEADLOCK} & a deadlock was detected while trying to acquire the lock \\ \hline \end{DoxyExceptions} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_mutex_a22c7752a61e7ae1e1c1e87a20b8dd0f4}\label{class_qore_1_1_thread_1_1_mutex_a22c7752a61e7ae1e1c1e87a20b8dd0f4}} \index{Qore::Thread::Mutex@{Qore::Thread::Mutex}!lock@{lock}} \index{lock@{lock}!Qore::Thread::Mutex@{Qore::Thread::Mutex}} \doxysubsubsection{\texorpdfstring{lock()}{lock()}\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}} {\footnotesize\ttfamily \mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} Qore\+::\+Thread\+::\+Mutex\+::lock (\begin{DoxyParamCaption}\item[{timeout}]{timeout\+\_\+ms }\end{DoxyParamCaption})} Locks the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object; blocks if the lock is already held. An optional timeout value may be passed to this method, giving a time in milliseconds to wait for the lock to become free. Like all Qore functions and methods taking \mbox{\hyperlink{data_type_declarations_timeout_type}{timeout}} values, a \mbox{\hyperlink{basic_data_types_relative_dates}{relative time value}} may be passed instead of an integer to make the timeout units clear To release the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}}, use \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a23adbdd9cd3ffe17b1cbc700716aec5c}{Mutex\+::unlock()}} \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{\textcolor{keywordflow}{if} (mutex.lock(1250ms))} \DoxyCodeLine{ throw \textcolor{stringliteral}{"{}TIMEOUT-\/ERROR"{}}, \textcolor{stringliteral}{"{}lock acquisition timed out after 1.25s"{}};} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyParams}{Parameters} {\em timeout\+\_\+ms} & a \mbox{\hyperlink{data_type_declarations_timeout_type}{timeout}} value to wait to acquire the lock; integers are interpreted as milliseconds; \mbox{\hyperlink{basic_data_types_relative_dates}{relative date/time values}} are interpreted literally (with a resolution of milliseconds)\\ \hline \end{DoxyParams} \begin{DoxyReturn}{Returns} returns -\/1 for error, 0 for success \end{DoxyReturn} \begin{DoxyExceptions}{Exceptions} {\em LOCK-\/\+ERROR} & lock called twice in the same thread, object deleted in another thread, etc \\ \hline {\em THREAD-\/\+DEADLOCK} & a deadlock was detected while trying to acquire the lock \\ \hline \end{DoxyExceptions} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_mutex_abcc3818211d37882c0549bfcbe7c487b}\label{class_qore_1_1_thread_1_1_mutex_abcc3818211d37882c0549bfcbe7c487b}} \index{Qore::Thread::Mutex@{Qore::Thread::Mutex}!trylock@{trylock}} \index{trylock@{trylock}!Qore::Thread::Mutex@{Qore::Thread::Mutex}} \doxysubsubsection{\texorpdfstring{trylock()}{trylock()}} {\footnotesize\ttfamily \mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} Qore\+::\+Thread\+::\+Mutex\+::trylock (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Acquires the lock only if it is not already held; returns 0 for success (lock acquired) or -\/1 if the call would block. \begin{DoxyReturn}{Returns} 0 for success (lock acquired) or -\/1 if the call would block (lock not acquired) \end{DoxyReturn} \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{int i = mutex.trylock();} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyExceptions}{Exceptions} {\em LOCK-\/\+ERROR} & object deleted in another thread, etc \\ \hline {\em THREAD-\/\+DEADLOCK} & a deadlock was detected while trying to acquire the lock \\ \hline \end{DoxyExceptions} \mbox{\Hypertarget{class_qore_1_1_thread_1_1_mutex_a23adbdd9cd3ffe17b1cbc700716aec5c}\label{class_qore_1_1_thread_1_1_mutex_a23adbdd9cd3ffe17b1cbc700716aec5c}} \index{Qore::Thread::Mutex@{Qore::Thread::Mutex}!unlock@{unlock}} \index{unlock@{unlock}!Qore::Thread::Mutex@{Qore::Thread::Mutex}} \doxysubsubsection{\texorpdfstring{unlock()}{unlock()}} {\footnotesize\ttfamily nothing Qore\+::\+Thread\+::\+Mutex\+::unlock (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})} Unlocks the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} object; wakes up one thread if any threads are blocked on this lock. \begin{DoxyParagraph}{Example\+:} \begin{DoxyCode}{0} \DoxyCodeLine{mutex.unlock();} \end{DoxyCode} \end{DoxyParagraph} \begin{DoxyExceptions}{Exceptions} {\em LOCK-\/\+ERROR} & unlock called by a thread that does not own the lock or the lock is not locked, object deleted in another thread, etc \\ \hline \end{DoxyExceptions}