18 PSpace synchronous bind methods

PSpace methods

These are the methods on a PSpace which allow for synchronously binding the IPersistable object with a given OID.

$adt+ PSpace
{
    ...
    ptr<IPersistable> BindObject(OID oid);
    ptr<IPersistable> BindObjectIfMemoryResident(OID oid);
    ptr<IPersistable> TryBindObject(OID oid);
    void MakeMemoryResident(OID oid);
};

ptr<IPersistable> BindObject(OID oid)

Bind to the IPersistable object for the given oid which must not be null. A lock on the PSpace is required.

First checks whether the object is currently resident in memory. If not then loads the object from disk. Throws a DerefDanglingOidException if object not found in the LSS.

May throw

• TypeMismatchException
• DerefDanglingOidException
• DeserialisePersistentObjectException
• DeserialisationException
• EndOfStreamException

Never returns null.

ptr<IPersistable> BindObjectIfMemoryResident(OID oid)

Get the object with the given oid (which must not be null) if it is resident in memory, otherwise returns null.

Doesn't make any attempt to load the object into memory from disk.

A lock on the PSpace is required.

ptr<IPersistable> TryBindObject(OID oid)

Like BindObject() except returns null if no object with the given oid exists in the LSS, rather than throwing DerefDanglingOidException

void MakeMemoryResident(OID oid)

Usually called without a lock on the PSpace. Tries to ensure that the object with the given OID is resident in memory. Therefore this function may block on I/O. The implementation may very briefly get a lock on the PSpace.

Free functions using the PSpace in thread local storage

$function+ ptr<IPersistable> BindObjectGivenOid(OID oid)
{
    return GetThreadPtr<PSpace>()->BindObject(oid);
}

$function+ ptr<IPersistable> BindObjectInMemoryGivenOid(OID oid)
{
    return GetThreadPtr<PSpace>()->BindObjectIfMemoryResident(oid);
}

$function+ ptr<IPersistable> TryBindObjectGivenOid(OID oid)
{
    return GetThreadPtr<PSpace>()->TryBindObject(oid);
}

$function+ ptr<IPersistable> BindObjectGivenOid(OID oid)

Bind to the IPersistable object for the given oid which must not be null.

First checks whether the object is currently resident in memory. If not then loads the object from disk. Throws a DerefDanglingOidException if object not found in the LSS.

May throw

• TypeMismatchException
• DerefDanglingOidException
• DeserialisePersistentObjectException
• DeserialisationException
• EndOfStreamException

This function requires that the calling thread has set the PSpace in which po persists (or will persist) in thread local storage when this function is called. See SetThreadPSpace() or SetThreadPtr<PSpace>().

$function+ ptr<IPersistable> BindObjectInMemoryGivenOid(OID oid)

Bind to the IPersistable object for the given oid which must not be null.

Only binds to the object if it's currently resident in memory. Otherwise returns null. Doesn't make any attempt to load the object into memory from disk.

$function+ ptr<IPersistable> TryBindObjectGivenOid(OID oid)

Same as BindObjectGivenOid() except returns null for a 'dangling oid' (i.e. an oid not found in the LSS) rather than throwing a DerefDanglingOidException.

Methods on pref/cref which synchronously return the IPersistable object

Application developers don't usually call the above methods directly, instead the corresponding methods on a pref or cref are normally used.

template<typename T>
class pref
{
    ...
    ptr<T> GetBoundPtr() const;         // Returns m_ptr
    ptr<T> GetInMemory() const;         // BindObjectInMemoryGivenOid
    ptr<T> Get() const;                 // BindObjectGivenOid
    ptr<T> GetNotNull() const;          // Get() or throw DerefNullPrefException
    ptr<T> TryGet() const;              // TryBindObjectGivenOid

    T operator*() const { return *GetNotNull(); }
    ptr<T> operator->() const { return GetNotNull(); }
};

template<typename T>
class cref
{
    ...
    T* GetBoundPtr() const;         // Returns m_ptr
    T* GetInMemory() const;         // BindObjectInMemoryGivenOid
    T* Get() const;                 // BindObjectGivenOid
    T* GetNotNull() const;          // Get() or throw DerefNullPrefException
    T* TryGet() const;              // TryBindObjectGivenOid

    T& operator*() const { return *GetNotNull(); }
    T* operator->() const { return GetNotNull(); }
};