1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::SharedMemory)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
(Shared Memory Memory)
manpagename(FBB::SharedMemory)(Shared Memory memory structure)
manpagesynopsis()
bf(#include <bobcat/sharedmemory>)nl()
Linking option: tt(-lbobcat )
manpagedescription()
The class bf(FBB::SharedMemory) implements a usable interface to a shared
memory segment made available by tt(FBB::SharedSegment) and monitored by
tt(FBB::SharedPos). It is the main building block for
tt(FBB::SharedBuf), defining the `device' to which
tt(FBB::SharedBuf) interfaces. All shared memory related I/O should be
performed by bf(FBB::SharedMemory) objects, which are true objects, not
themselves residing in shared memory.
An bf(FBB::SharedMemory) object defines, connects to and manages access to
shared memory, encapsulating all raw shared memory operations. In addition to
the class bf(FBB::SharedMemory) the header file tt(bobcat/sharedmemory) also
defines a bf(struct SharedEnum__) defining bf(enum SizeUnit) within the
namespace tt(FBB).
The requested amount of shared memory is always a lower bound to the maximum
amount of shared memory that eventually may become available. When defining a
bf(SharedMemory) object not all of its potentially available shared memory is
immediately allocated. Shared memory will be allocated by the bf(SharedMemory)
object once needed (up to a calculated maximum).
As a fictitious example: assume 100 kB of memory is requested. The
bf(SharedMemory) object then maintains a table of, e.g., 10 entries, each
entry controlling access to a shared memory block of 10 kB. These 10 kB blocks
aren't immediately allocated, but become available once the program reads from
or writes to addresses located in these data blocks. Newly allocated data
blocks are initialized to 0-bytes.
Caveat: when constructing a shared memory segment make sure the segment's
ID is stored at a retrievable location. This allows other processes to access
the shared segment. The shared segment ID is also required to delete a shared
memory segment. If the shared segment ID is lost, the memory occupied by the
shared memory segment remains inaccessible (although they can be retrieved and
removed by additional means, like bf(ipcs)(1) and bf(ipcrm)(1)). The member
tt(id) returns the ID of the shared memory currently monitored by an
bf(FBB::SharedMemory) object.
includefile(include/namespace)
manpagesection(INHERITS FROM)
bf(FBB::SharedEnum__)
The bf(struct SharedEnum__) is a wrapper struct around bf(enum SizeUnit),
which is available through inheritance in several bf(FBB::Shared*) classes,
and offers symbolic constants defining standard memory sizes. The bf(enum
SizeUnit) defines the following symbolic constants:
itemization(
it() bf(kB), representing 1024 (2**10) bytes of memory;
it() bf(MB), representing 1048576 (2**20) bytes of memory;
it() bf(GB), representing 1073741824 (2**30) bytes of memory
)
manpagesection(CONSTRUCTORS, DESTRUCTOR)
itemization(
itb(SharedMemory())
The default constructor defines an empty stub, which cannot immediately
be used. As the bf(SharedMemory) class supports move assignment,
empty stubs can easily be (re)configured at any time after their
construction.
itb(SharedMemory(size_t maxSize, SizeUnit sizeUnit, size_t access = 0600))
This constructor creates a shared memory segment having a capacity of
at least tt(maxSize * sizeUnit) bytes. The shared memory's access
rights are defined by the tt(access) parameter, using the well-known
(bf(chmod)(1)) octal values to define access rights for the owner, the
group and others. If construction succeeds the shared memory is ready
for use. If construction fails, an tt(FBB::Exception) is thrown.
itb(SharedMemory(int id))
This constructor connects to a shared memory segment having ID
tt(id). If construction succeeds the shared memory is ready for
use. If construction fails (e.g., no shared memory segment having ID
tt(id) exists), an tt(FBB::Exception) is thrown.
itb(~SharedMemory())
The destructor detaches any attached shared memory segments from
the bf(FBB::SharedMemory) object. If the shared memory segment is
currently locked by the bf(FBB::SharedMemory) object, the lock is
removed.
)
Copy and move constructors (and assignment operators) are not available.
manpagesection(OVERLOADED OPERATORS)
itemization(
itb(std::ostream &operator<<(std::ostream &out,
SharedMemory const &sharedMemory))
The overloaded insertion operator inserts information about the
tt(SharedMemory) object into the provide tt(ostream) object. The IDs
of the shared segments, their sizes, the maximum number of shared
memory segments, the number of bytes that can be read from the shared
memory, and its actual storage capacity, etc., are displayed.
itb(SharedMemory &operator=(SharedMemory &&rhs))
The overloaded move assignment operator is available. It is used to
(re)define the shared memory segment an bf(FBB::SharedMemory) object
is interfacing with.
)
manpagesection(MEMBER FUNCTIONS)
itemization(
itb(size_t blockOffset() const)
The offset within the shared segment data block matching tt(offset)'s
return value is returned. 0 is returned if the bf(SharedMemory)
object has not yet been connected to a shared memory block (or if the
offset happens to be at the block's offset 0).
itb(void clear())
First, the shared memory is locked. Next, all shared data segment are
deleted, and the shared memory's own data are reset to indicate it is
completely empty. Following this the shared memory segment is unlocked
again. Returning from tt(clear) the shared memory The
bf(FBB::SharedMemory) object is effectively re-initialized, with
tt(offset) and tt(nReadable) returning 0.
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(size_t dataSegmentSize() const)
Returns the size (in bytes) of shared memory data block. 0 is returned
if the bf(SharedMemory) object has not yet been connected to a shared
memory block.
itb(int get())
First the bf(FBB::SharedMemory) object calls tt(lock) to lock the
shared memory segment. Next the character at tt(offset) is retrieved
and tt(offset) is incremented. Then tt(unlock) is called, and the
retrieved character is returned. If tt(offset) is at least equal to
tt(nReadable, EOF) is immediately returned.
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(int id() const)
The ID of the shared memory segment is returned. Following tt(kill)
tt(id) returns -1, indicating that the shared segment cannot be used
anymore (note that tt(operator=) can be used to re-initialize the
bf(FBB::SharedMemory) object).
itb(SharedType *install(std::streamsize *offset,
Params &&...params))
This member was implemented as a member template, using tt(typename
SharedType) and tt(typename ...Params), allowing perfect forwarding of
arguments to tt(SharedType)'s constructor.
This member installs a tt(SharedType) object at bf(SharedMemory's) at
bf(SharedMemory)'s first available offset: either at the current
offset, or (if tt(SharedType's) size is too big to fit in the current
data block at offset) at the first byte of the next tt(SharedSegment)
shared data block.
The actual offset where the tt(SharedType) object is installed is
returned in tt(*offset), unless a tt(nullptr) is passed as
tt(install's) first argument.
A pointer to the installed tt(SharedType) is returned, with
tt(shmem.offset) pointing just beyond tt(SharedType's) last byte.
The tt(SharedType) object is installed using placement new. E.g., the
following example illustrates how a bf(SharedMutex)(3bobcat) object
can be installed at the first possible
location of tt(SharedMemory shmem):
verb(
std::streamsize offset;
FBB::SharedMutex *mutexPtr = shmem.install<FBB::SharedMutex>(&offset);
)
If the installed object must be destroyed, its destructor must
explicitly be called. E.g., to destroy the tt(Mutex) pointed at by
tt(mutexPtr) use tt(mutexPtr->~SharedMutex()).
An tt(FBB::Exception) is thrown if tt(shmem) could not install the
object in its shared memory data blocks.
itb(void kill())
Without locking the shared memory all shared memory controlled by the
bf(SharedMemory) object is deleted. The bf(SharedMemory) object is
unusable after returning from tt(kill), with its tt(id) member returns
-1. Nothing happens if this member is called when the bf(SharedMemory)
object has not yet been connected to a shared memory block.
itb(std::streamsize maxOffset() const)
The maximum possible offset that can be used with the shared memory
segment is returned. The members tt(offset) and tt(nReadable) never
exceed the value returned by tt(maxOffset). 0 is returned if the
bf(SharedMemory) object has not yet been connected to a shared memory
block.
itb(std::streamsize nReadable() const)
The number of characters (bytes) that can be read from the beginning of
the shared memory is returned. 0 is returned if the bf(SharedMemory)
object has not yet been connected to a shared memory block.
itb(std::streamsize offset() const)
The offset within the shared memory segment (i.e., relative to the
segment's tt(ios::beg) position) is returned. 0 is returned if the
bf(SharedMemory) object has not yet been connected to a shared memory
block (or if the offset happens to be at the shared memory's offset
0).
itb(char *ptr())
Returns 0 if tt(offset() == maxOffset()). Otherwise it returns a
pointer to the character at index tt(offset) within the shared memory
segment.
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(int put(int ch))
After locking the appropriate shared data segment, tt(ch) is written at
position tt(offset), incrementing tt(offset) thereafter. If tt(ch ==
EOF, EOF) is immediately returned.
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(int read(Type *value))
This member was implemented as a member template. It calls
the next member, casting tt(Type *) to tt(char *), and using
tt(sizeof(Type)) as its second argument. The number of
bytes actually read is returned. This member returns -1 if
initially tt(offset) was at least equal to tt(nReadable).
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(int read(char *data, std::streamsize len))
While locking the appropriate shared data segment(s) at most tt(len)
bytes are read from the shared memory, starting at tt(offset). The
bytes read from shared memory are stored at tt(data). The number of
bytes actually read is returned. This member returns -1 if
initially tt(offset) was at least equal to tt(nReadable).
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(int read(std::ios::off_type offset, Type *value,
std::ios::seekdir origin = std::ios::beg))
This member was implemented as a member template. After changing the
bf(SharedMemory)'s offset to tt(offset) (relative to tt(origin)), it
calls the first tt(read) member, passing it tt(value). The number of
bytes actually read is returned. This member returns -1 if initially
tt(offset) was at least equal to tt(nReadable).
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(void remove())
The shared memory is locked, after which all shared memory controlled
by the bf(FBB::SharedMemory) object is deleted. The
bf(FBB::SharedMemory) object is unusable after returning from
tt(remove).
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(std::ios::pos_type seek(std::ios::off_type offset,
std::ios::seekdir origin = std::ios::beg))
Moves the tt(offset) position relative to tt(way). The value -1 is
returned when seeking before offset 0 or beyond tt(maxOffset),
otherwise the offset relative to the begin location of the shared
memory (i.e, tt(offset) for tt(origin == ios::beg)) is returned. 0 is
returned if the bf(SharedMemory) object has not yet been connected to
a shared memory block (or if the offset happens to be at the shared
memory's offset 0).
itb(std::streamsize showmanyc() const)
The number of characters that can be read from the current shared
segment data block is returned. This member interrogates the number
of readable characters in the shared memory segment. This number may
change while this member is being executed. In order to receive a
stable return value, calling functions should have obtained a lock on
the shared memory segment before calling this member. 0 is returned if
the bf(SharedMemory) object has not yet been connected to a shared
memory block (or if the no characters can currently be read).
itb(void swap(SharedMemory &other))
The current and other bf(FBB::SharedMemory) objects are swapped.
itb(bool truncate(std::streamsize offset))
If tt(offset) is not exceeding the value returned by tt(nReadable)
tt(nReadable) is changed to tt(offset) and tt(true) is
returned. Otherwise tt(false) is returned, and the value returned by
tt(nReadable) is not changed.
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(int write(Type const *value))
This member was implemented as a member template. It calls the next
member, casting tt(Type const *) to tt(char const *), and using
tt(sizeof(Type)) as its second argument. The number of bytes actually
written is returned. This member returns -1 if initially tt(offset)
was at least equal to tt(maxOffset).
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(int write(char const *data, std::streamsize len))
The bf(FBB::SharedMemory) object calls tt(lock) to lock the shared
memory, and writes at most tt(len) bytes into the shared memory,
starting at tt(offset). Next, tt(unlock) is called. The number of
bytes actually written is returned. The member function returns -1 if
initially tt(offset) is equal to tt(maxOffset).
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
itb(int write(std::ios::off_type offset, Type const *value,
std::ios::seekdir origin = std::ios::beg))
This member was implemented as a member template. After changing the
bf(SharedMemory)'s offset to tt(offset) (relative to tt(origin)), it
calls the first tt(write) member, passing it tt(value). The number of
bytes actually written is returned. This member returns -1 if
initially tt(offset) was at least equal to tt(maxOffset).
An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
yet been connected to a shared memory block.
)
manpagesection(EXAMPLE)
See the bf(sharedstream)(3bobcat) man page.
manpagefiles()
em(bobcat/sharedmemory) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(chmod)(1), bf(ipcs)(1), bf(ipcrm)(1),
bf(isharedstream)(3bobcat),
bf(osharedstream)(3bobcat),
bf(sharedblock)(3bobcat),
bf(sharedcondition)(3bobcat),
bf(sharedmutex)(3bobcat),
bf(sharedpos)(3bobcat),
bf(sharedreadme)(7bobcat),
bf(sharedsegment)(3bobcat),
bf(sharedstream)(3bobcat),
bf(sharedbuf)(3bobcat)
manpagebugs()
None Reported.
includefile(include/trailer)
|
