HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups 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  * {
20  * A() { myProxy = UT_ProxyPointer::allocProxy(this); }
21  * ~A() { UT_ProxyPointer::freeProxy(myProxy); }
22  * };
23  *
24  * class B
25  * {
26  * B(int proxy) { myPointer=UT_ProxyPointer::reference(proxy); }
27  * ~B() { UT_ProxyPointer::deReference(myPointer); }
28  * A *getA() { return (A *)UT_ProxyPointer::lookup(myPointer); }
29  * };
30  * main()
31  * {
32  * A *a;
33  * B *b0, *b1;
34  * a = new A();
35  * b0 = new B(a->myProxy);
36  * b1 = new B(a->myProxy);
37  * fprintf(stderr, "0x%08x\n", b0->getA()); delete b0;
38  * delete a;
39  * fprintf(stderr, "0x%08x\n", b1->getA()); delete b1;
40  * }
41  *
42  * NOTE: This class mainly provides a defense against poor programming.
43  * However, it can provide memory efficiency since this allows links to be
44  * built between objects without maintining double links. The cost here is
45  * that there are multiple de-references instead of a single de-reference of
46  * the pointer, meaning that cache performance is impacted. As well, more
47  * null pointer checking needs to be performed.
48  */
49 
50 #ifndef __UT_ProxyPointer__
51 #define __UT_ProxyPointer__
52 
53 #include "UT_API.h"
54 
56 {
57 public:
58  // The source object can use this class to allocate a proxy pointer
59  static int allocProxy(void *ptr);
60  static void freeProxy(int &id);
61 
62  // This ID is guaranteed (well pretty much) to be an invalid id.
63  static inline int nullId() { return -1; }
64  static inline int isValid(int id) { return id >= 0; }
65 
66  // When a class needs to reference the proxy, they should make sure to
67  // reference/de-reference the proxy properly.
68  static void referenceProxy(int id);
69  static void deReferenceProxy(int id);
70 
71  //
72  // Swizzling the pointer allows you to change the object the proxy points
73  // to so that all references to the pointer will be updated to the new
74  // pointer.
75  static void swizzlePointer(int id, void *ptr);
76 
77  // This method can be used to get the pointer out of the proxy. If the
78  // source object has been free'd a null pointer (i.e. 0) will be returned.
79  static void *lookupProxy(int id);
80 
81  // For some odd reason, you may want to know if there are other people
82  // referencing the proxy. This method will return the number of references
83  // to the proxy (including yourself).
84  static unsigned getReferenceCount(int id);
85 };
86 
87 #endif
static int isValid(int id)
#define UT_API
Definition: UT_API.h:14
static int nullId()
auto ptr(T p) -> const void *
Definition: format.h:4331