librnr  1.14.5
RoadNarrows Robotics Common Library 1
shm.h
Go to the documentation of this file.
1 ////////////////////////////////////////////////////////////////////////////////
2 /*! \file
3  *
4  * \brief Shared memory interface.
5  *
6  * \pkgsynopsis
7  * RoadNarrows Robotics Common Library 1
8  *
9  * \pkgcomponent{Library}
10  * librnr
11  *
12  * \pkgfile{rnr/shm.h}
13  *
14  * \author Robin Knight (robin.knight@roadnarrows.com)
15  *
16  * \pkgcopyright{2013-2018,RoadNarrows LLC.,http://www.roadnarrows.com}
17  *
18  * \license{MIT}
19  *
20  * \EulaBegin
21  * See the README and EULA files for any copyright and licensing information.
22  * \EulaEnd
23  */
24 ////////////////////////////////////////////////////////////////////////////////
25 
26 #ifndef _RNR_SHM_H
27 #define _RNR_SHM_H
28 
29 #include <sys/ipc.h>
30 #include <sys/shm.h>
31 
32 #include "rnr/rnrconfig.h"
33 
34 C_DECLS_BEGIN
35 
36 /*!
37  * \brief Shared memory structure type.
38  */
39 typedef struct
40 {
41  key_t m_shmKey; ///< shared memory key
42  int m_shmId; ///< shared memory identifier
43  size_t m_shmSize; ///< shared memory size in bytes
44  void *m_shmAddr; ///< starting addressed of attached shared memory
45 } shm_t;
46 
47 /*!
48  * \brief Shared memory pthread mutex structure type.
49  */
50 typedef shm_t shm_mutex_t;
51 
52 /*!
53  * \brief User-supplied shared memory initialization function.
54  *
55  * \param key Shared memory key.
56  * \param addr Starting address of attached shared memory.
57  * \param size Shared memory size.
58  */
59 typedef void (*shm_mem_init_func_t)(key_t key, void *add, size_t size);
60 
61 
62 #ifndef SHM_MUTEX_N_TRIES
63 #define SHM_MUTEX_N_TRIES 3 ///< maximum number of tries to acquire lock
64 #endif
65 
66 #ifndef SHM_MUTEX_T_TRIES
67 #define SHM_MUTEX_T_TRIES 50000 ///< usec time between tries to acquire lock
68 #endif
69 
70 /*!
71  * \brief Open shared memory segement.
72  *
73  * If the segment, associated by key, does not exist, then the shared memory is
74  * created and, optionally, initialized.
75  *
76  * The shared memory segment is attached to the application address space.
77  *
78  * \param key Shared memory key.
79  * \param size Shared memory size.
80  * \param mem_init Optional memory initializer function. Set to NULL for
81  * no initialization.
82  * \param [in,out] pshm Pointer to shared memory structure defined in caller's
83  * space.
84  *
85  * \return On success, returns \ref OK(0).\n
86  * On failure, errno is set and \ref RC_ERROR(-1) is returned.
87  */
88 extern int shm_open(key_t key,
89  size_t size,
90  shm_mem_init_func_t mem_init,
91  shm_t *pshm);
92 
93 /*!
94  * \brief Close shared memory segement.
95  *
96  * The segment is marked for deletion, and is actually destroy after the last
97  * process detaches.
98  *
99  * \param [in,out] pshm Pointer to shared memory structure defined in caller's
100  * space.
101  *
102  * \return On success, returns \ref OK(0).\n
103  * On failure, errno is set and \ref RC_ERROR(-1) is returned.
104  */
105 extern int shm_close(shm_t *pshm);
106 
107 /*!
108  * \brief Create and initialize a shared memory mutex.
109  *
110  * \param key Shared memory key.
111  * \param [in,out] pshmmutex Pointer to shared memory mutext structure defined
112  * in caller's space.
113  *
114  * \return On success, returns 0.\n
115  * On failure, errno is set and returned.
116  */
117 extern int shm_mutex_init(key_t key, shm_mutex_t *pshmmutex);
118 
119 /*!
120  * \brief Destroy a shared memory mutex.
121  *
122  * The mutex is actually only destroyed when the last process attached to this
123  * mutex calls destroy.
124  *
125  * \param [in,out] pshmmutex Pointer to shared memory mutext structure defined
126  * in caller's space.
127  *
128  * \return On success, returns 0.\n
129  * On failure, errno is set and returned.
130  */
131 extern int shm_mutex_destroy(shm_mutex_t *pshmmutex);
132 
133 /*!
134  * \brief Lock the mutex.
135  *
136  * \param [in] pshmmutex Pointer to shared memory mutext structure defined
137  * in caller's space.
138  *
139  * \return On success, returns 0.\n
140  * On failure, errno is set and returned.
141  */
142 extern int shm_mutex_lock(shm_mutex_t *pshmmutex);
143 
144 /*!
145  * \brief Try to lock the mutex.
146  *
147  * \param [in] pshmmutex Pointer to shared memory mutext structure defined
148  * in caller's space.
149  *
150  * \return On success, returns 0.\n
151  * If the mutex is already locked, EBUSY is returned.\n
152  * Otherwise, on failure, errno is set and returned.
153  */
154 extern int shm_mutex_trylock(shm_mutex_t *pshmmutex);
155 
156 /*!
157  * \brief Unlock a lock the mutex.
158  *
159  * \param [in] pshmmutex Pointer to shared memory mutext structure defined
160  * in caller's space.
161  *
162  * \return On success, returns 0.\n
163  * On failure, errno is set and returned.
164  */
165 extern int shm_mutex_unlock(shm_mutex_t *pshmmutex);
166 
167 C_DECLS_END
168 
169 
170 #endif // _RNR_SHM_H
171 
shm_open
int shm_open(key_t key, size_t size, shm_mem_init_func_t mem_init, shm_t *pshm)
Open shared memory segement.
Definition: shm.c:74
shm_mutex_init
int shm_mutex_init(key_t key, shm_mutex_t *pshmmutex)
Create and initialize a shared memory mutex.
Definition: shm.c:277
shm_mutex_t
shm_t shm_mutex_t
Shared memory pthread mutex structure type.
Definition: shm.h:50
shm_mem_init_func_t
void(* shm_mem_init_func_t)(key_t key, void *add, size_t size)
User-supplied shared memory initialization function.
Definition: shm.h:59
shm_t
Shared memory structure type.
Definition: shm.h:39
C_DECLS_BEGIN
#define C_DECLS_BEGIN
C declaration block begin in C.
Definition: rnrconfig.h:71
shm_close
int shm_close(shm_t *pshm)
Close shared memory segement.
Definition: shm.c:178
rnrconfig.h
RoadNarrows Robotics common configuration file.
shm_t::m_shmId
int m_shmId
shared memory identifier
Definition: shm.h:42
C_DECLS_END
#define C_DECLS_END
C declaration block end in C.
Definition: rnrconfig.h:72
shm_mutex_lock
int shm_mutex_lock(shm_mutex_t *pshmmutex)
Lock the mutex.
Definition: shm.c:305
shm_mutex_unlock
int shm_mutex_unlock(shm_mutex_t *pshmmutex)
Unlock a lock the mutex.
Definition: shm.c:396
shm_t::m_shmKey
key_t m_shmKey
shared memory key
Definition: shm.h:41
shm_mutex_destroy
int shm_mutex_destroy(shm_mutex_t *pshmmutex)
Destroy a shared memory mutex.
Definition: shm.c:300
shm_mutex_trylock
int shm_mutex_trylock(shm_mutex_t *pshmmutex)
Try to lock the mutex.
Definition: shm.c:350
shm_t::m_shmSize
size_t m_shmSize
shared memory size in bytes
Definition: shm.h:43
shm_t::m_shmAddr
void * m_shmAddr
starting addressed of attached shared memory
Definition: shm.h:44