/* 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_ */