CSpace

A CSpace is a space of objects protected by a single mutex, where each object implements the interface named IObject.

A CSpace (optionally) has its own garbage collector - there is a worker thread that periodically performs a stop the world tracing collection.

The main components of a CSpace are the following:

• Mutex : To protect access to the objects
• GCRoots : The set of roots for a GC
• GCThread : Worker thread to periodically run a GC
• GCExtent : The set of all the objects in the CSpace, needed for the sweep phase.

A given IObject can belong to at most one CSpace at a time.

The function CreateCSpace creates a CSpace.

The function TransferCSpace transfers all the objects from one CSpace into another (to obtain a merge of the two CSpaces).

Typically when using a CSpace the thread has a pointer to the CSpace set in thread local storage.

Objects are normally registered in a CSpace when they are first created using $new.

A CSpace is a $adt

$adt+ CSpace
{
    void Destroy();
    void EvictAllDgsNodes();
    ssize_t TryEvictDgsNodes(ssize_t maxNumDgsNodesToRetain);
    bool WaitForGarbageCollect();
    void Lock(ECSpaceLockMode mode);
    void Unlock();
    LockInfo BeginUnlock();
    void EndUnlock(LockInfo info);
    void AddGcRoot(ptr<const IObject> object);
    void RemoveGcRoot(ptr<const IObject> object);
    void StartGc();
    void StopGc();
    void RegisterGcObject(ptr<IObject> object);
    void RegisterNonGcObject(ptr<IObject> object);
    ssize_t GetNumObjects() const;
    void SynchronousGc();
    ssize_t GetMaxNumDgsNodesToRetain() const;
    void SetMaxNumDgsNodesToRetain(ssize_t n);
    int32 GetMilliSecsPerGc() const;
    void SetMilliSecsPerGc(int32 t);
    ssize_t GetEvictionThreshold() const;
    void SetEvictionThreshold(ssize_t totalSizeInBytes);
    int64 GetTotalNumCompletedGcs() const;
    void** GetPtrSlotArray();
};

See the following sections for descriptions of the methods:

• CSpace mutex
• GCRoots
• GCExtent
• CSpace DGS functions

---

void Destroy()

Every CSpace must eventually be destroyed. The CSpace must not be locked (except perhaps internally by the GC thread)

---

bool WaitForGarbageCollect()

Typically called from a custom GC thread function

CSpace tracing garbage collector

Rate at which garbage collections are performed

A CSpace defines a rate at which garbage collections are performed, in terms of the period in milliseconds between garbage collections.

The following threadsafe functions are used to get/set the time between garbage collections for a given CSpace:

---

int32 GetMilliSecsPerGc() const

Get the time per GC in milliseconds. No lock is required. This function is threadsafe.

---

void SetMilliSecsPerGc(int32 t)

Set the time per GC in milliseconds. No lock is required. This function is threadsafe. Note for testing: if t < 0 then garbage collections will be performed in a tight loop without a call to sleep to give up the timeslice. This allows for agressive garbage collection code to help show up racing conditions.

Starting and stopping the garbage collector thread

---

void StartGc()

Start the GC thread.

---

void StopGc()

Stop the GC thread.

GC stats

The following function provides stats about the GCs

---

int64 GetTotalNumCompletedGcs() const

Get the total number of completed garbage collections that have been performed on the CSpace.

Object eviction

A CSpace supports weak references to evictable objects. A CSpace has a setting that affects the number of evictable objects to keep resident in memory.

During a GC the CSpace measures the total size of all resident evictable objects (using the size set by calls to SetEvictableObjectSizeInBytes(), and evicts on an LRU basis until the total size is below the eviction threshold.

---

ssize_t GetEvictionThreshold() const

Get the eviction threshold for this CSpace.

---

void SetEvictionThreshold(ssize_t totalSizeInBytes)

Set the eviction threshold for this CSpace.