# 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;
    };