179 lines
4.3 KiB
C
179 lines
4.3 KiB
C
/* 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);
|
|
|
|
|
|
/**
|
|
* Predicate returns TRUE when the current thread owns the mutex
|
|
*/
|
|
sos_bool_t sos_kmutex_owned_by_me(struct sos_kmutex const* 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_ */
|