\hypertarget{class_qore_1_1_thread_1_1_mutex}{}\section{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}
\subsection*{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}


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

\begin{DoxyParagraph}{Restrictions\+:}
\mbox{\hyperlink{group__parse__options_gade963e1fbbd1f5b2c777df7221512a1b}{Qore\+::\+P\+O\+\_\+\+N\+O\+\_\+\+T\+H\+R\+E\+A\+D\+\_\+\+C\+L\+A\+S\+S\+ES}}
\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 L\+O\+C\+K-\/\+E\+R\+R\+OR} 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 A\+PI, 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}{P\+O\+\_\+\+N\+O\+\_\+\+T\+H\+R\+E\+A\+D\+\_\+\+C\+L\+A\+S\+S\+ES}} parse option 
\end{DoxyNote}


\subsection{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}}
\subsubsection{\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}}
\subsubsection{\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}}
\subsubsection{\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 L\+O\+C\+K-\/\+E\+R\+R\+OR} & 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}}
\subsubsection{\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 L\+O\+C\+K-\/\+E\+R\+R\+OR} & lock called twice in the same thread, object deleted in another thread, etc \\
\hline
{\em T\+H\+R\+E\+A\+D-\/\+D\+E\+A\+D\+L\+O\+CK} & 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}}
\subsubsection{\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 L\+O\+C\+K-\/\+E\+R\+R\+OR} & lock called twice in the same thread, object deleted in another thread, etc \\
\hline
{\em T\+H\+R\+E\+A\+D-\/\+D\+E\+A\+D\+L\+O\+CK} & 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}}
\subsubsection{\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 L\+O\+C\+K-\/\+E\+R\+R\+OR} & object deleted in another thread, etc \\
\hline
{\em T\+H\+R\+E\+A\+D-\/\+D\+E\+A\+D\+L\+O\+CK} & 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}}
\subsubsection{\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 L\+O\+C\+K-\/\+E\+R\+R\+OR} & 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}
