1 files changed, 172 insertions, 0 deletions
diff --git a/sos-code-article6.75/sos/ksynch.h b/sos-code-article6.75/sos/ksynch.h
new file mode 100644
index 0000000..47d8675
--- /dev/null
+++ b/sos-code-article6.75/sos/ksynch.h
@@ -0,0 +1,172 @@
+/* Copyright (C) 2004 David Decotigny
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+   
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+   
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, write to the Free Software
+   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
+   USA. 
+*/
+#ifndef _SOS_KSYNCH_H_
+#define _SOS_KSYNCH_H_
+
+
+/**
+ * @file synch.h
+ *
+ * Common kernel synchronisation primitives.
+ */
+
+
+#include <sos/errno.h>
+#include <sos/kwaitq.h>
+
+
+/* ====================================================================
+ * Kernel semaphores, NON-recursive
+ */
+
+
+/**
+ * The structure of a (NON-RECURSIVE) kernel Semaphore
+ */
+struct sos_ksema
+{
+  int value;
+  struct sos_kwaitq kwaitq;
+};
+
+
+/*
+ * Initialize a kernel semaphore structure with the given name
+ *
+ * @param name Name of the semaphore (for debugging purpose only; safe
+ * [deep copied])
+ *
+ * @param initial_value The value of the semaphore before any up/down
+ */
+sos_ret_t sos_ksema_init(struct sos_ksema *sema, const char *name,
+			 int initial_value,
+			 sos_kwaitq_ordering_t ordering);
+
+
+/*
+ * De-initialize a kernel semaphore
+ *
+ * @return -SOS_EBUSY when semaphore could not be de-initialized
+ * because at least a thread is in the waitq.
+ */
+sos_ret_t sos_ksema_dispose(struct sos_ksema *sema);
+
+
+/*
+ * Enters the semaphore
+ *
+ * @param timeout Maximum time to wait for the semaphore. Or NULL for
+ * "no limit". Updated on return to reflect the time remaining (0 when
+ * timeout has been triggered)
+ *
+ * @return -SOS_EINTR when timeout was triggered or when another waitq
+ * woke us up.
+ *
+ * @note This is a BLOCKING FUNCTION
+ */
+sos_ret_t sos_ksema_down(struct sos_ksema *sema,
+			 struct sos_time *timeout);
+
+
+/*
+ * Try to enter the semaphore without blocking.
+ *
+ * @return -SOS_EBUSY when locking the semaphore would block
+ */
+sos_ret_t sos_ksema_trydown(struct sos_ksema *sema);
+
+
+/**
+ * Increments the semaphore's value, eventually waking up a thread
+ */
+sos_ret_t sos_ksema_up(struct sos_ksema *sema);
+
+
+
+/* ====================================================================
+ * Kernel mutex (ie binary semaphore with strong ownership),
+ * NON-recursive !
+ */
+
+
+/**
+ * The structure of a (NON-RECURSIVE) kernel Mutex
+ */
+struct sos_kmutex
+{
+  struct sos_thread  *owner;
+  struct sos_kwaitq  kwaitq;
+};
+
+
+/*
+ * Initialize a kernel mutex structure with the given name
+ *
+ * @param name Name of the mutex (for debugging purpose only; safe
+ * [deep copied])
+ *
+ * @param initial_value The value of the mutex before any up/down
+ */
+sos_ret_t sos_kmutex_init(struct sos_kmutex *mutex, const char *name,
+			  sos_kwaitq_ordering_t ordering);
+
+
+/*
+ * De-initialize a kernel mutex
+ *
+ * @return -SOS_EBUSY when mutex could not be de-initialized
+ * because at least a thread is in the waitq.
+ */
+sos_ret_t sos_kmutex_dispose(struct sos_kmutex *mutex);
+
+
+/*
+ * Lock the mutex. If the same thread multiply locks the same mutex,
+ * it won't hurt (no deadlock, return value = -SOS_EBUSY).
+ *
+ * @param timeout Maximum time to wait for the mutex. Or NULL for "no
+ * limit". Updated on return to reflect the time remaining (0 when
+ * timeout has been triggered)
+ *
+ * @return -SOS_EINTR when timeout was triggered or when another waitq
+ * woke us up, -SOS_EBUSY when the thread already owns the mutex.
+ *
+ * @note This is a BLOCKING FUNCTION
+ */
+sos_ret_t sos_kmutex_lock(struct sos_kmutex *mutex,
+			  struct sos_time *timeout);
+
+
+/*
+ * Try to lock the mutex without blocking.
+ *
+ * @return -SOS_EBUSY when locking the mutex would block
+ */
+sos_ret_t sos_kmutex_trylock(struct sos_kmutex *mutex);
+
+
+/**
+ * Unlock the mutex, eventually waking up a thread
+ *
+ * @return -SOS_EPERM when the calling thread is NOT the owner of the
+ * mutex
+ */
+sos_ret_t sos_kmutex_unlock(struct sos_kmutex *mutex);
+
+
+#endif /* _SOS_KSYNCH_H_ */