\doxysection{Qore\+::Thread\+::Mutex Class Reference}
\hypertarget{class_qore_1_1_thread_1_1_mutex}{}\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.  




{\ttfamily \#include $<$QC\+\_\+\+Mutex.\+dox.\+h$>$}



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}
\doxysubsubsection*{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 \doxylink{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 \doxylink{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 
\mbox{\hyperlink{group__type__conversion__functions_ga9a401e5112c58f63c05e7ee1e15968ef}{nothing}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a0bb3432456ccdf0cfb1523429b5b4141}{lock}} ()
\begin{DoxyCompactList}\small\item\em Locks the \doxylink{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}} (\mbox{\hyperlink{group__type__conversion__functions_ga9a401e5112c58f63c05e7ee1e15968ef}{timeout}} \mbox{\hyperlink{group__type__conversion__functions_ga9a401e5112c58f63c05e7ee1e15968ef}{timeout\+\_\+ms}})
\begin{DoxyCompactList}\small\item\em Locks the \doxylink{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 
\mbox{\hyperlink{group__type__conversion__functions_ga9a401e5112c58f63c05e7ee1e15968ef}{nothing}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a23adbdd9cd3ffe17b1cbc700716aec5c}{unlock}} ()
\begin{DoxyCompactList}\small\item\em Unlocks the \doxylink{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*{Public Member Functions inherited from \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Qore\+::\+Thread\+::\+Abstract\+Smart\+Lock}}}
\begin{DoxyCompactItemize}
\item 
\mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock_af15ccf8b346a9f3abbbdc559d2f5e59b}{constructor}} ()
\begin{DoxyCompactList}\small\item\em Throws an exception if called directly; this class can only be instantiated by builtin subclasses. \end{DoxyCompactList}\item 
\mbox{\hyperlink{group__type__conversion__functions_gacf16b4126b795f4b6933ef3425cadae3}{string}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock_aaf6a2ecab96ad01d3ab0dbb81b63a363}{get\+Name}} ()
\begin{DoxyCompactList}\small\item\em Returns the name of the threading class directly inheriting this class. \end{DoxyCompactList}\item 
\mbox{\hyperlink{group__type__conversion__functions_ga9a401e5112c58f63c05e7ee1e15968ef}{bool}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock_a4936d08a0508d61a41e8c685e2a03d72}{lock\+Owner}} ()
\begin{DoxyCompactList}\small\item\em Returns \doxysectlink{basic_data_types_True}{True}{2} if the calling thread owns the lock, \doxysectlink{basic_data_types_False}{False}{2} if not. \end{DoxyCompactList}\item 
\mbox{\hyperlink{group__type__conversion__functions_ga2de8717e92c5f97ccc6511f6062d6502}{int}} \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_smart_lock_afafe6ef19203993a7c5dd87e00068325}{lock\+TID}} ()
\begin{DoxyCompactList}\small\item\em Returns the TID of the thread owning the lock or -\/1 if the lock is currently not acquired. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
A class providing an implementation for a simple thread lock. 

\begin{DoxyParagraph}{Restrictions\+:}
\doxylink{group__parse__options_gade963e1fbbd1f5b2c777df7221512a1b}{Qore\+::\+PO\+\_\+\+NO\+\_\+\+THREAD\+\_\+\+CLASSES}
\end{DoxyParagraph}
\begin{DoxyParagraph}{Overview}
This class inherits \doxylink{class_qore_1_1_thread_1_1_abstract_smart_lock}{Abstract\+Smart\+Lock}, so it can be used by \doxylink{class_qore_1_1_thread_1_1_condition}{Condition} objects.~\newline
~\newline
 The \doxylink{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 \doxylink{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 \doxylink{class_qore_1_1_thread_1_1_auto_lock}{Auto\+Lock} class for a class that assists in exception-\/safe \doxylink{class_qore_1_1_thread_1_1_mutex}{Mutex} locking.~\newline
~\newline
 Additionally, the \doxysectlink{statements_on_exit}{on\+\_\+exit statement}{1} can provide exception-\/safe unlocking at the lexical block level for \doxylink{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 \doxylink{class_qore_1_1_thread_1_1_mutex}{Mutex} class manages the lock as a \doxysectlink{threading_thread_resources}{thread resource}{1}; if the lock is not released when the thread exits (or when \doxylink{group__threading__functions_ga421dca39ccb55b191d5d09fd98c2075a}{Qore\+::throw\+\_\+thread\+\_\+resource\+\_\+exceptions()} or \doxylink{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 \doxylink{class_qore_1_1_thread_1_1_mutex}{Mutex} class does not inherit \doxylink{class_qore_1_1_thread_1_1_abstract_thread_resource}{Abstract\+Thread\+Resource} explicitly as a part of the exported API, and the internal \doxylink{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 \doxylink{group__parse__options_gade963e1fbbd1f5b2c777df7221512a1b}{PO\+\_\+\+NO\+\_\+\+THREAD\+\_\+\+CLASSES} parse option 
\end{DoxyNote}


\doxysubsection{Member Function Documentation}
\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 \doxylink{class_qore_1_1_thread_1_1_mutex}{Mutex} object. 

\begin{DoxyParagraph}{Example\+:}

\begin{DoxyCode}{0}
\DoxyCodeLine{Mutex\ mutex();}

\end{DoxyCode}
 
\end{DoxyParagraph}
\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 \doxylink{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}
\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}
\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 \mbox{\hyperlink{group__type__conversion__functions_ga9a401e5112c58f63c05e7ee1e15968ef}{nothing}} Qore\+::\+Thread\+::\+Mutex\+::lock (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})}



Locks the \doxylink{class_qore_1_1_thread_1_1_mutex}{Mutex} object; blocks if the lock is already held. 

To release the \doxylink{class_qore_1_1_thread_1_1_mutex}{Mutex}, use \doxylink{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}
\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[{\mbox{\hyperlink{group__type__conversion__functions_ga9a401e5112c58f63c05e7ee1e15968ef}{timeout}}}]{timeout\+\_\+ms }\end{DoxyParamCaption})}



Locks the \doxylink{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 \doxysectlink{data_type_declarations_timeout_type}{timeout}{1} values, a \doxysectlink{basic_data_types_relative_dates}{relative time value}{2} may be passed instead of an integer to make the timeout units clear

To release the \doxylink{class_qore_1_1_thread_1_1_mutex}{Mutex}, use \doxylink{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 \doxysectlink{data_type_declarations_timeout_type}{timeout}{1} value to wait to acquire the lock; integers are interpreted as milliseconds; \doxysectlink{basic_data_types_relative_dates}{relative date/time values}{2} 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}
\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}
\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 \mbox{\hyperlink{group__type__conversion__functions_ga9a401e5112c58f63c05e7ee1e15968ef}{nothing}} Qore\+::\+Thread\+::\+Mutex\+::unlock (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})}



Unlocks the \doxylink{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}
