From cad626fa9792abb74b861c6d0c1444d58188c002 Mon Sep 17 00:00:00 2001
From: Amlal El Mahrouss <amlal@nekernel.org>
Date: Fri, 1 Aug 2025 10:34:07 +0100
Subject: feat: tex: add binary_mutex document.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>
---
 docs/tex/binary_mutex.tex | 65 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 docs/tex/binary_mutex.tex

(limited to 'docs')

diff --git a/docs/tex/binary_mutex.tex b/docs/tex/binary_mutex.tex
new file mode 100644
index 00000000..5902cefc
--- /dev/null
+++ b/docs/tex/binary_mutex.tex
@@ -0,0 +1,65 @@
+\documentclass{article}
+\usepackage{graphicx} % Required for inserting images
+
+\title{The BinaryMutex Pattern}
+\author{Amlal El Mahrouss}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{Context}
+
+The BinaryMutex is a core component of NeKernel (NeKernel/VMKernel) based systems.
+
+The pattern excludes other acquirers to own the USER\_PROCESS that is currently being hold.
+
+Thus the acquiree is the USER\_PROCESS itself
+
+\section{Use Cases}
+
+\begin{verbatim}
+BinaryMutex mux;
+mux.Lock(process);
+
+// Say we want to interact with the process itself on this thread, 
+we can then make sure that no race condition happens by using:
+constexpr auto kSecondsMax = 5;
+mux.WaitForProcess(kSecondsMax); 
+\end{verbatim}
+
+\section{Implementation}
+
+The source implementation consists of:
+
+\begin{verbatim}
+class BinaryMutex final {
+ public:
+  explicit BinaryMutex() = default;
+  ~BinaryMutex()         = default;
+
+ public:
+  bool IsLocked() const;
+  bool Unlock() noexcept;
+
+ public:
+  BOOL WaitForProcess(const UInt32& sec) noexcept;
+
+ public:
+  bool Lock(USER_PROCESS* process);
+  bool LockOrWait(USER_PROCESS* process, TimerInterface* timer);
+
+ public:
+  NE_COPY_DEFAULT(BinaryMutex)
+
+ private:
+  USER_PROCESS* fLockingProcess;
+};
+\end{verbatim}
+
+\section{Conclusion}
+
+This pattern is useful for systems that need to make sure that a process isn't tampered by concurrent usages. Thus its existence in VMKernel and NeKernel.
+
+\end{document}
-- 
cgit v1.2.3