source: trunk/kernel/libk/remote_condvar.h @ 576

Last change on this file since 576 was 563, checked in by alain, 6 years ago

Complete restructuration of kernel spinlocks.
File size: 7.4 KB
Line 
1/*
2 * remote_condvar.h: POSIX condition variable definition.     
3 *
4 * Authors  Alain Greiner (2016,2017,2018)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-kernel; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _CONDVAR_H_
25#define _CONDVAR_H_
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29#include <remote_busylock.h>
30#include <xlist.h>
31
32/*******************************************************************************************
33 *     This file define an user level POSIX compliant condition variable.
34 *
35 * It can be used by muti-threaded user applications to synchronise user threads
36 * running in different clusters.
37 *
38 * A condvar is declared by a given user process as a "pthread_cond_t" global variable.
39 * This user type is implemented as an unsigned long, but the value is not used by the
40 * kernel. ALMOS-MKH uses only the mutex virtual address as an identifier.
41 * For each user condvar, ALMOS-MKH creates a kernel "remote_condvar_t" structure,
42 * dynamically allocated in the reference cluster by the remote_condvar_create() function,
43 * and destroyed by the remote_condvar_destroy() function, using RPC if the calling thread
44 * is not running in the reference cluster.
45 *
46 * The blocking "remote_condvar_wait() function allowx the calling thread to efficiently
47 * wait for a change in a shared user object. The calling thread blocks and register in
48 * a waiting queue attached to the condvar. The blocked thread is unblocked by another
49 * thread calling the remote_convar signal() or remote_condvar_broadcast().
50 * The three associated methods wait(), signal() and broadcast() must be called
51 * by a thread holding the mutex associated to the condvar.
52 ******************************************************************************************/
53
54/*******************************************************************************************
55 * This structure defines the kernel implementation of a condvar.
56 ******************************************************************************************/
57
58typedef struct remote_condvar_s
59{
60    remote_busylock_t lock;         /*! lock protecting the condvar state                 */
61    intptr_t          ident;        /*! virtual address in user space == identifier       */
62    xlist_entry_t     root;         /*! root of waiting threads queue                     */
63    xlist_entry_t     list;         /*! member of list of condvars in same process        */
64}
65remote_condvar_t;
66
67/*********************************************************************************************
68 * This function returns an extended pointer on the remote condvar identified
69 * by its virtual address in a given user process. It makes an associative search,
70 * scanning the list of user condvars rooted in the reference process descriptor.
71 *********************************************************************************************
72 * @ ident    : semaphore virtual address, used as identifier.
73 * @ returns extended pointer on semaphore if success / returns XPTR_NULL if not found.
74 ********************************************************************************************/
75xptr_t remote_condvar_from_ident( intptr_t  ident );
76
77/*******************************************************************************************
78 * This function implements the CONVAR_INIT operation.
79 * This function creates and initializes a remote_condvar, identified by its virtual
80 * address <vaddr> in the client process reference cluster, using RPC if required.
81 * It registers this user condvar in the reference process descriptor.
82 *******************************************************************************************
83 * @ vaddr         : [in]  condvar virtual addresss, used as identifier.
84 ******************************************************************************************/
85error_t remote_condvar_create( intptr_t   vaddr );
86
87/*******************************************************************************************
88 * This function implements the CONVAR_DESTROY operation.
89 * This function creates and initializes a remote_condvar, identified by its virtual
90 * address in the client process reference cluster, and registers it in process descriptor.
91 *******************************************************************************************
92 * @ condvar_xp : [in] extended pointer on buffer to store xptr on created condvar.
93 ******************************************************************************************/
94void remote_condvar_destroy( xptr_t condvar_xp );
95
96/*******************************************************************************************
97 * This function implements the CONDVAR_WAIT operation.
98 * It atomically releases the mutex identified by the <mutex_xp> argument,
99 * registers the calling thread in the condvar waiting queue identified by the
100 * <condvar_xp> argument, blocks and deschedules this calling thread.
101 * Later, when the calling thread resume, this function re-acquire the mutex and returns.
102 * WARNING: the calling thread must hold the mutex associated to the condvar.
103 *******************************************************************************************
104 * @ condvar_xp : [in] extended pointer on condvar.
105 * @ mutex_xp   : [in] extended pointer on mutex.
106 ******************************************************************************************/
107void remote_condvar_wait( xptr_t condvar_xp,
108                          xptr_t mutex_xp );
109
110/*******************************************************************************************
111 * This function implements the CONDVAR_SIGNAL operation.
112 * It remove one waiting thread from a remote_condvar waiting queue identified by the
113 * <condvar_xp> argument and unblocks this thread.
114 * It does nothing if the queue is empty.
115 * WARNING: the calling thread must hold the mutex associated to the condvar.
116 *******************************************************************************************
117 * @ condvar_xp : extended pointer on remote_condvar.
118 ******************************************************************************************/
119void remote_condvar_signal( xptr_t condvar_xp );
120
121/*******************************************************************************************
122 * This function implements the CONDVAR_BROADCAST operation.
123 * It removes all threads from a remote_condvar waiting queue identified by the
124 * <condvar_xp> argument, and unblocks all these threads.
125 * It does nothing if the queue is empty.
126 * WARNING: the calling thread must hold the mutex associated to the condvar.
127 *******************************************************************************************
128 * @ condvar_xp : extended pointer on remote_condvar.
129 ******************************************************************************************/
130void remote_condvar_broadcast( xptr_t condvar_xp );
131
132#endif  /* _CONDVAR_H_ */
Note: See TracBrowser for help on using the repository browser.