EAGlobal

Introduction

EAGlobal provides the GlobalPtr class. GlobalPtr acts as a reference to a pointer which is global throughout the process (includes the application and any loaded DLLs). The object pointed to must define a unique 32-bit kGlobalID if one is not given. The GlobalPtr class works in a way similar to a smart pointer, but note that it is not the same as your typical auto_ptr or anything else provided by C++ library vendors. The pointer is set to NULL on creation.

Global pointers may be used from multiple threads once initialized to point to an object, but are _not_ thread-safe when being set. If you have a situation where two threads may attempt to set a global pointer at the same time, you should use OS globals (See EAOSGlobal.h) instead to serialize the creators on the OS global lock and prevent race conditions.

A GlobalPtr is not the same thing as simply declaring a pointer at a globally accessible scope, especially on platforms with dynamic libraries such as Windows with its DLLs. A GlobalPtr allows multiple pieces of code to declare independent pointers to an object, even if the pieced of code are in independent DLLs.

The pointer assigned to a GlobalPointer need not be a pointer allocated dynamically on the heap. It can just as well be the address of some static or local variable.

Example usage

Here we provide some basic example usage.

GlobalPtr<int, 0x11111111> pInteger;
GlobalPtr<int, 0x11111111> pInteger2;

assert(pInteger == NULL);

pInteger = new int[2];
pInteger[0] = 10;
pInteger[1] = 20;
assert(pInteger2 == pInteger);
assert(pInteger2[0] == pInteger[0]);

delete[] pInteger;
pInteger = NULL;
assert(pInteger2 == NULL);

Interface

The GlobalPtr class works like a smart pointer, but note that it is not the same as your typical auto_ptr or anything else provided by C++ library vendors.

template<class t, uint32_t kGlobalId = T::kGlobalId>
class GlobalPtr
{
public:
    /// this_type
    /// This is an alias for this class.
    typedef GlobalPtr<T, kGlobalId> this_type;

    /// GlobalPtr
    ///
    /// Default constructor. Sets member pointer to whatever the 
    /// shared version is. If this is the first usage of the shared
    /// version, the pointer will be set to NULL.
    ///
    /// Example usage:
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass;
    ///
    GlobalPtr();

    /// GlobalPtr (copy constructor)
    ///
    /// Default constructor. Sets member pointer to whatever the 
    /// shared version is. If this is the first usage of the shared
    /// version, the pointer will be set to NULL.
    ///
    /// Example usage:
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass1;
    ///    pSomeClass1 = new pSomeClass;
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass2(pSomeClass1);
    ///    pSomeClass2->DoSomething();
    ///
    explicit GlobalPtr(const this_type& globalPtr);

    /// operator =
    ///
    /// Example usage:
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass1;
    ///    pSomeClass1 = new pSomeClass;
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass2(pSomeClass1);
    ///    pSomeClass2->DoSomething();
    ///
    this_type& operator=(const this_type& /*globalPtr*/);

    /// operator =
    ///
    /// Example usage:
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass1;
    ///    pSomeClass1 = new pSomeClass;
    ///    delete pSomeClass1;
    ///    pSomeClass1 = new pSomeClass;
    ///
    this_type& operator=(T* p);

    /// operator T*
    ///
    /// Example usage:
    ///    GlobalPtrlt;SomeClass, 0x12345678> pSomeClass;
    ///    FunctionWhichUsesSomeClassPtr(pSomeClass);
    ///
    operator T*() const;

    /// operator T*
    ///
    /// Example usage:
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass;
    ///    CallFunctionWhichUsesSomeClassPtr(pSomeClass);
    ///
    T& operator*() const;

    /// operator ->
    ///
    /// Example usage:
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass;
    ///    pSomeClass->DoSomething();
    ///
    T* operator->() const;

    /// operator !
    ///
    /// Example usage:
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass;
    ///    if(!pSomeClass)
    ///        pSomeClass = new SomeClass;
    ///
    bool operator!() const;

    /// get
    ///
    /// Returns the owned pointer.
    ///
    /// Example usage:
    ///    GlobalPtr<SomeClass, 0x12345678> pSomeClass = new SomeClass;
    ///    SomeClass* pSC = pSomeClass.get();
    ///    pSC->DoSomething();
    ///
    T* get() const;
};