ucommon  7.0.0
About: GNU uCommon C++ is a portable and optimized class framework for writing C++ applications that need to use threads and support concurrent synchronization, and that use sockets, XML parsing, object serialization, thread-optimized string and data structure classes, etc..
  Fossies Dox: ucommon-7.0.0.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

Loading...
Searching...
No Matches
object.h
Go to the documentation of this file.
1// Copyright (C) 1999-2005 Open Source Telecom Corporation.
2// Copyright (C) 2006-2014 David Sugar, Tycho Softworks.
3// Copyright (C) 2015 Cherokees of Idaho.
4//
5// This program is free software; you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation; either version 2 of the License, or
8// (at your option) any later version.
9//
10// This program is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU Lesser General Public License
16// along with this program. If not, see <http://www.gnu.org/licenses/>.
17//
18// As a special exception, you may use this file as part of a free software
19// library without restriction. Specifically, if other files instantiate
20// templates or use macros or inline functions from this file, or you compile
21// this file and link it with other files to produce an executable, this
22// file does not by itself cause the resulting executable to be covered by
23// the GNU General Public License. This exception does not however
24// invalidate any other reasons why the executable file might be covered by
25// the GNU General Public License.
26//
27// This exception applies only to the code released under the name GNU
28// Common C++. If you copy code from other releases into a copy of GNU
29// Common C++, as the General Public License permits, the exception does
30// not apply to the code that you add in this way. To avoid misleading
31// anyone as to the status of such modified files, you must delete
32// this exception notice from them.
33//
34// If you write modifications of your own for GNU Common C++, it is your choice
35// whether to permit this exception to apply to your modifications.
36// If you do not wish that, delete this exception notice.
37//
38
39/**
40 * @file object.h
41 * @short Some object manipulation classes for smart pointers, linked lists,
42 * etc.
43 **/
44
45#ifndef COMMONCPP_OBJECT_H_
46#define COMMONCPP_OBJECT_H_
47
48#ifndef COMMONCPP_CONFIG_H_
49#include <commoncpp/config.h>
50#endif
51
52namespace ost {
53
54class MapObject;
55class MapIndex;
56
57/**
58 * A reference countable object. This is used in association with smart
59 * pointers (RefPointer).
60 *
61 * @author David Sugar <dyfet@gnutelephony.org>
62 * @short Object managed by smart pointer reference count.
63 */
65{
66private:
68
69protected:
70 friend class RefPointer;
71
72 unsigned refCount;
73
74 /**
75 * The constructor simply initializes the count.
76 */
77 inline RefObject() {
78 refCount = 0;
79 }
80
81 /**
82 * The destructor is called when the reference count returns
83 * to zero. This is done through a virtual destructor.
84 */
85 virtual ~RefObject();
86
87public:
88 /**
89 * The actual object being managed can be returned by this
90 * method as a void and then recast to the actual type. This
91 * removes the need to dynamic cast from RefObject and the
92 * dependence on rtti this implies.
93 *
94 * @return underlying object being referenced.
95 */
96 virtual void *getObject(void) = 0;
97};
98
99/**
100 * Pointer to reference counted objects. This is a non-template form
101 * of a reference count smart pointer, and so uses common code. This
102 * can be subclassed to return explicit object types.
103 *
104 * @author David Sugar <dyfet@gnutelephony.org>
105 * @short Pointer to reference count managed objects.
106 */
108{
109protected:
111
112 /**
113 * Detach current object, for example, when changing pointer.
114 */
115 void detach(void);
116
117 /**
118 * Patch point for mutex in derived class. This may often
119 * be a single static mutex shared by a managed type.
120 */
121 virtual void enterLock(void);
122
123 /**
124 * Patch point for a mutex in derived class. This may often
125 * be a single static mutex shared by a managed type.
126 */
127 virtual void leaveLock(void);
128
129public:
130 /**
131 * Create an unattached pointer.
132 */
133 inline RefPointer() {
134 ref = NULL;
135 }
136
137 /**
138 * Create a pointer attached to a reference counted object.
139 *
140 * Object being referenced.
141 */
142 RefPointer(RefObject *obj);
143
144 /**
145 * A copy constructor.
146 *
147 * Pointer being copied.
148 */
149 RefPointer(const RefPointer &ptr);
150
151 virtual ~RefPointer();
152
154
155 inline void *operator*() const {
156 return getObject();
157 }
158
159 void *getObject(void) const;
160
161 operator bool() const;
162
163 bool operator!() const;
164};
165
166/**
167 * Self managed single linked list object chain. This is used for
168 * accumulating lists by using as a base class for a derived subclass.
169 *
170 * @author David Sugar <dyfet@gnutelephony.org>
171 * @short Accumulating single linked list.
172 */
174{
175private:
177
178protected:
180
181 inline LinkedSingle() {
182 nextObject = NULL;
183 }
184
185 virtual ~LinkedSingle();
186
187public:
188 /**
189 * Get first linked object in list. This may be dynamically
190 * recast, and may refer to a master static bookmark pointer
191 * in a derived class. Otherwise it simply returns the current
192 * object. In a "free" list, this may not only return the first
193 * object, but also set the first to next.
194 *
195 * @return pointer to first object in list.
196 */
197 virtual LinkedSingle *getFirst(void);
198
199 /**
200 * Gets the last object in the list. This normally follows the
201 * links to the end. This is a virtual because derived class
202 * may include a static member bookmark for the current end.
203 *
204 * @return pointer to last object in list.
205 */
206 virtual LinkedSingle *getLast(void);
207
208 /**
209 * Get next object, for convenience. Derived class may use
210 * this with a dynamic cast.
211 *
212 * @return next object in list.
213 */
214 inline LinkedSingle *getNext(void) {
215 return nextObject;
216 }
217
218 /**
219 * Insert object into chain. This is a virtual because
220 * derived class may choose instead to perform an insert
221 * at head or tail, may manage bookmarks, and may add mutex lock.
222 *
223 * @param object being inserted.
224 */
225 virtual void insert(LinkedSingle& obj);
226
228};
229
230/**
231 * Self managed double linked list object chain. This is used for
232 * accumulating lists by using as a base class for a derived subclass.
233 *
234 * @author David Sugar <dyfet@gnutelephony.org>
235 * @short Accumulating double linked list.
236 */
238{
239private:
241
242protected:
244
245 inline LinkedDouble() {
246 nextObject = prevObject = NULL;
247 }
248
249 virtual ~LinkedDouble();
250
251 virtual void enterLock(void);
252
253 virtual void leaveLock(void);
254
255 virtual LinkedDouble *firstObject();
256
257 virtual LinkedDouble *lastObject();
258
259public:
260
261 /**
262 * Requested in overloaded insert() method to indicate how to insert
263 * data into list
264 */
266 {
267 modeAtFirst, /**< insert at first position in list pointed by current object */
268 modeAtLast, /**< insert at last position in list pointed by current object */
269 modeBefore, /**< insert in list before current object */
270 modeAfter /**< insert in list after current object */
271 };
272
273 /**
274 * Get first linked object in list. This may be dynamically
275 * recast, and may refer to a master static bookmark pointer
276 * in a derived class. Otherwise it follows list to front.
277 *
278 * @return pointer to first object in list.
279 */
280 virtual LinkedDouble *getFirst(void);
281
282 /**
283 * Gets the last object in the list. This normally follows the
284 * links to the end. This is a virtual because derived class
285 * may include a static member bookmark for the current end.
286 *
287 * @return pointer to last object in list.
288 */
289 virtual LinkedDouble *getLast(void);
290
291 /**
292 * Virtual to get the insert point to use when adding new members. This
293 * may be current, or always head or always tail. As a virtual, this allows
294 * derived class to establish "policy".
295 *
296 * @return pointer to insertion point in list.
297 */
298 virtual LinkedDouble *getInsert(void);
299
300 /**
301 * Get next object, for convenience. Derived class may use
302 * this with a dynamic cast.
303 *
304 * @return next object in list.
305 */
306 inline LinkedDouble *getNext(void) {
307 return nextObject;
308 }
309
310 /**
311 * Get prev object in the list.
312 *
313 * @return pointer to previous object.
314 */
315 inline LinkedDouble *getPrev(void) {
316 return prevObject;
317 }
318
319 /**
320 * Insert object into chain at given pos, as indicated by \ref InsertMode;
321 * If no pos is given, it defaults to \ref modeAtLast, inserting element
322 * at list's end.
323 *
324 * @param object being inserted.
325 * @param position where object is inserted.
326 */
327 virtual void insert(LinkedDouble& obj, InsertMode position = modeAtLast);
328
329 /**
330 * Remove object from chain.
331 */
332 virtual void detach(void);
333
335
336 LinkedDouble &operator--();
337};
338
339/**
340 * A map table allows for entities to be mapped (hash index) onto it.
341 * Unlike with Assoc, This form of map table also allows objects to be
342 * removed from the table. This table also includes a mutex lock for
343 * thread safety. A free list is also optionally maintained for reusable
344 * maps.
345 *
346 * @author David Sugar <dyfet@gnutelephony.org>
347 * @short Table to hold hash indexed objects.
348 */
349class __EXPORT MapTable : public Mutex
350{
351private:
353
354protected:
355 friend class MapObject;
356 friend class MapIndex;
357 unsigned range;
358 unsigned count;
360
361 void cleanup(void);
362
363public:
364 /**
365 * Create a map table with a specified number of slots.
366 *
367 * @param number of slots.
368 */
369 MapTable(unsigned size);
370
371 /**
372 * Destroy the table, calls cleanup.
373 */
374 virtual ~MapTable();
375
376 /**
377 * Get index value from id string. This function can be changed
378 * as needed to provide better collision avoidence for specific
379 * tables.
380 *
381 * @param id string
382 * @return index slot in table.
383 */
384 virtual unsigned getIndex(const char *id);
385
386 /**
387 * Return range of this table.
388 *
389 * @return table range.
390 */
391 inline unsigned getRange(void) {
392 return range;
393 }
394
395 /**
396 * Return the number of object stored in this table.
397 *
398 * @return table size.
399 */
400 inline unsigned getSize(void) {
401 return count;
402 }
403
404 /**
405 * Lookup an object by id key. It is returned as void * for
406 * easy re-cast.
407 *
408 * @param key to find.
409 * @return pointer to found object or NULL.
410 */
411 void *getObject(const char *id);
412
413 /**
414 * Map an object to our table. If it is in another table
415 * already, it is removed there first.
416 *
417 * @param object to map.
418 */
419 void addObject(MapObject &obj);
420 /**
421 * Get the first element into table, it is returned as void * for
422 * easy re-cast.
423 *
424 * @return pointer to found object or NULL.
425 */
426 void *getFirst();
427
428 /**
429 * Get the last element into table, it is returned as void * for
430 * easy re-cast.
431 *
432 * @return pointer to found object or NULL.
433 */
434 void *getLast();
435
436 /**
437 * Get table's end, useful for cycle control; it is returned as void * for
438 * easy re-cast.
439 *
440 * @return pointer to found object or NULL.
441 */
442 void *getEnd() {
443 return NULL;
444 }
445
446 /**
447 * Get next object from managed free list. This returns as a
448 * void so it can be recast into the actual type being used in
449 * derived MapObject's. A derived version of MapTable may well
450 * offer an explicit type version of this. Some derived
451 * MapObject's may override new to use managed list.
452 *
453 * @return next object on free list.
454 */
455 void *getFree(void);
456
457 /**
458 * Add an object to the managed free list. Some MapObject's
459 * may override delete operator to detach and do this.
460 *
461 * @param object to add.
462 */
463 void addFree(MapObject *obj);
464
465 /**
466 * An operator to map an object to the table.
467 *
468 * @return table being used.
469 * @param object being mapped.
470 */
472
473 /**
474 * This operator is virtual in case it must also add the object to a
475 * managed free list.
476 *
477 * @return current table.
478 * @param object entity to remove.
479 */
480 virtual MapTable &operator-=(MapObject &obj);
481};
482
483/**
484 * The MapIndex allows linear access into a MapTable, that otherwise could have
485 * its elements being retrieved only by key.
486 * It can be increased, checked and dereferenced like a pointer, by means of
487 * suitable operators.
488 *
489 * @author Sergio Repetto <s.repetto@pentaengineering.it>
490 * @short Index object to access MapTable elements
491 */
493{
495
496public :
497
498 /**
499 * Creates an empty map index (pointing to nothing).
500 */
501 MapIndex() : thisObject(NULL) {}
502
503 /**
504 * Creates a map index pointing to a specific map object
505 *
506 * @param the indexed object
507 */
508 MapIndex(MapObject* theObject) : thisObject(theObject) {}
509
510 /**
511 * Creates a copy of a given map index
512 *
513 * @param the source index object
514 */
515 MapIndex(const MapIndex& theIndex) : thisObject(theIndex.thisObject) {}
516
517 /**
518 * Dereference operator: the pointed object it is returned as void * for
519 * easy re-cast.
520 *
521 * @return pointer to indexed object.
522 */
523 void* operator*() const {
524 return (void*)thisObject;
525 }
526
527 /**
528 * Assignment operator to avoid implicit cast.
529 *
530 * @return the object itself, as changed.
531 */
532 MapIndex& operator=(MapObject *theObject);
533
534 /**
535 * Prefix increment operator, to be used in loops and such.
536 *
537 * @return the object itself, as changed.
538 */
539 MapIndex& operator++(); // prefix
540
541 /**
542 * Postfix increment operator, to be used in loops and such.
543 *
544 * @return the object itself, as changed.
545 */
546 MapIndex operator++(int) { // postfix
547 return this->operator++();
548 }
549
550 /**
551 * Comparison operator, between two MapIndex's.
552 *
553 * @return the object itself, as changed.
554 */
555 bool operator==(const MapIndex& theIndex) const {
556 return thisObject == theIndex.thisObject;
557 }
558
559 bool operator!=(const MapIndex& theIndex) const {
560 return !(*this == theIndex);
561 }
562
563 /**
564 * Comparison operator, between the MapIndex and a MapObject, useful to avoid
565 * casts for sake of clearness.
566 *
567 * @return the object itself, as changed.
568 */
569 bool operator==(const MapObject* theObject) const {
570 return thisObject == theObject;
571 }
572
573 bool operator!=(const MapObject* theObject) const {
574 return !(*this == theObject);
575 }
576};
577
578/**
579 * The MapObject is a base class which can be used to make a derived
580 * class operate on a MapTable. Derived classes may override new and
581 * delete operators to use managed free list from a MapTable.
582 *
583 * @author David Sugar <dyfet@gnutelephony.org>
584 * @short Mappable object.
585 */
587{
588private:
590
591protected:
592 friend class MapTable;
593 friend class MapIndex;
595 const char *idObject;
597
598public:
599
600 /**
601 * Remove the object from it's current table.
602 */
603 void detach(void);
604
605 /**
606 * Save id, mark as not using any table.
607 *
608 * @param id string for this object.
609 */
610 MapObject(const char *id);
611};
612
613} // namespace ost
614
615#endif
Self managed double linked list object chain.
Definition: object.h:238
InsertMode
Requested in overloaded insert() method to indicate how to insert data into list.
Definition: object.h:266
@ modeAtLast
insert at last position in list pointed by current object
Definition: object.h:268
@ modeBefore
insert in list before current object
Definition: object.h:269
@ modeAtFirst
insert at first position in list pointed by current object
Definition: object.h:267
__DELETE_COPY(LinkedDouble)
LinkedDouble * nextObject
Definition: object.h:243
LinkedDouble * getNext(void)
Get next object, for convenience.
Definition: object.h:306
LinkedDouble * getPrev(void)
Get prev object in the list.
Definition: object.h:315
Self managed single linked list object chain.
Definition: object.h:174
__DELETE_COPY(LinkedSingle)
LinkedSingle * getNext(void)
Get next object, for convenience.
Definition: object.h:214
LinkedSingle * nextObject
Definition: object.h:179
The MapIndex allows linear access into a MapTable, that otherwise could have its elements being retri...
Definition: object.h:493
bool operator==(const MapObject *theObject) const
Comparison operator, between the MapIndex and a MapObject, useful to avoid casts for sake of clearnes...
Definition: object.h:569
MapIndex(const MapIndex &theIndex)
Creates a copy of a given map index.
Definition: object.h:515
bool operator!=(const MapObject *theObject) const
Definition: object.h:573
bool operator!=(const MapIndex &theIndex) const
Definition: object.h:559
MapIndex()
Creates an empty map index (pointing to nothing).
Definition: object.h:501
bool operator==(const MapIndex &theIndex) const
Comparison operator, between two MapIndex's.
Definition: object.h:555
MapIndex(MapObject *theObject)
Creates a map index pointing to a specific map object.
Definition: object.h:508
void * operator*() const
Dereference operator: the pointed object it is returned as void * for easy re-cast.
Definition: object.h:523
MapObject * thisObject
Definition: object.h:494
MapIndex operator++(int)
Postfix increment operator, to be used in loops and such.
Definition: object.h:546
The MapObject is a base class which can be used to make a derived class operate on a MapTable.
Definition: object.h:587
MapObject * nextObject
Definition: object.h:594
__DELETE_COPY(MapObject)
MapTable * table
Definition: object.h:596
const char * idObject
Definition: object.h:595
A map table allows for entities to be mapped (hash index) onto it.
Definition: object.h:350
void * getEnd()
Get table's end, useful for cycle control; it is returned as void * for easy re-cast.
Definition: object.h:442
__DELETE_COPY(MapTable)
unsigned getSize(void)
Return the number of object stored in this table.
Definition: object.h:400
unsigned count
Definition: object.h:358
MapObject ** map
Definition: object.h:359
unsigned getRange(void)
Return range of this table.
Definition: object.h:391
unsigned range
Definition: object.h:357
A reference countable object.
Definition: object.h:65
unsigned refCount
Definition: object.h:72
RefObject()
The constructor simply initializes the count.
Definition: object.h:77
__DELETE_COPY(RefObject)
virtual void * getObject(void)=0
The actual object being managed can be returned by this method as a void and then recast to the actua...
Pointer to reference counted objects.
Definition: object.h:108
RefObject * ref
Definition: object.h:110
RefPointer()
Create an unattached pointer.
Definition: object.h:133
RefPointer & operator=(const RefObject &ref)
void * operator*() const
Definition: object.h:155
#define __EXPORT
Definition: config.h:49
static void cleanup(void)
Definition: keywait.cpp:43
Definition: address.cpp:63
std::string & operator+=(std::string &target, String &source)
Definition: stream.h:581