HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
UT_ProxyPointer.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT_ProxyPointer.h ( UT Library, C++)
7  *
8  * COMMENTS: A proxy pointer is used when you have other objects referencing
9  * a source object. In many cases, it's possible for the source object to
10  * be destroyed leaving dangling references to the now deleted source
11  * object.
12  * This class allows the source object to obtain a "proxy" pointer that
13  * the other objects can reference. When the source object is deleted, it
14  * should clear the proxy pointer so that all referencing objects will get
15  * a null pointer (instead of a pointer to garbage memory).
16  *
17  * Example:
18  * class A {
19  * A() { myProxy = UT_ProxyPointer::allocProxy(this); }
20  * ~A() { UT_ProxyPointer::freeProxy(myProxy); }
21  * };
22  *
23  * class B {
24  * B(int proxy) { myPointer=UT_ProxyPointer::reference(proxy); }
25  * ~B() { UT_ProxyPointer::deReference(myPointer); }
26  * A *getA() { return (A *)UT_ProxyPointer::lookup(myPointer); }
27  * };
28  * main()
29  * {
30  * A *a;
31  * B *b0, *b1;
32  * a = new A();
33  * b0 = new B(a->myProxy);
34  * b1 = new B(a->myProxy);
35  * fprintf(stderr, "0x%08x\n", b0->getA()); delete b0;
36  * delete a;
37  * fprintf(stderr, "0x%08x\n", b1->getA()); delete b1;
38  * }
39  *
40  * NOTE: This class mainly provides a defense against poor programming.
41  * However, it can provide memory efficiency since this allows links to be
42  * built between objects without maintining double links. The cost here is
43  * that there are multiple de-references instead of a single de-reference of
44  * the pointer, meaning that cache performance is impacted. As well, more
45  * null pointer checking needs to be performed.
46  */
47 
48 #ifndef __UT_ProxyPointer__
49 #define __UT_ProxyPointer__
50 
51 #include "UT_API.h"
52 
54 public:
55  // The source object can use this class to allocate a proxy pointer
56  static int allocProxy(void *ptr);
57  static void freeProxy(int &id);
58 
59  // This ID is guaranteed (well pretty much) to be an invalid id.
60  static inline int nullId() { return -1; }
61  static inline int isValid(int id) { return id >= 0; }
62 
63  // When a class needs to reference the proxy, they should make sure to
64  // reference/de-reference the proxy properly.
65  static void referenceProxy(int id);
66  static void deReferenceProxy(int id);
67 
68  //
69  // Swizzling the pointer allows you to change the object the proxy points
70  // to so that all references to the pointer will be updated to the new
71  // pointer.
72  static void swizzlePointer(int id, void *ptr);
73 
74  // This method can be used to get the pointer out of the proxy. If the
75  // source object has been free'd a null pointer (i.e. 0) will be returned.
76  static void *lookupProxy(int id);
77 
78  // For some odd reason, you may want to know if there are other people
79  // referencing the proxy. This method will return the number of references
80  // to the proxy (including yourself).
81  static unsigned getReferenceCount(int id);
82 };
83 
84 #endif
static int isValid(int id)
png_voidp ptr
Definition: png.h:2145
#define UT_API
Definition: UT_API.h:12
static int nullId()