Class Implementation

Macros
#define	objInstCreate(clsname)   (clsname*)_objInstCreate(&objClassInfoName(clsname))
#define	objInstInit(inst)   _objInstInit(objInstBase(inst), (inst)->_clsinfo)
#define	_objinit_guaranteed   _Post_equal_to_(true)
#define	_objfactory_guaranteed   _Ret_valid_
#define	_objfactory_check   _Ret_opt_valid_ _Check_return_

Functions
intptr	objDefaultCmp (void *self, void *other, uint32 flags)
uint32	objDefaultHash (void *self, uint32 flags)

Detailed Description

Functions and macros for implementing classes and interfaces. These should only be used within class implementation files, not by code that merely uses objects.

IMPORTANT: Do not call these functions from outside class factory functions and implementation code. Regular object users should use the public API (objAcquire, objRelease, etc.).

Macro Definition Documentation

_objfactory_check

#define _objfactory_check   _Ret_opt_valid_ _Check_return_

SAL annotation indicating factory function may fail

Use for factory functions that can fail and return NULL. Callers must check the return value.

Definition at line 110 of file objimpl.h.

_objfactory_guaranteed

#define _objfactory_guaranteed   _Ret_valid_

SAL annotation indicating factory function always succeeds

Use for factory functions that are guaranteed to return a valid object (never NULL).

Definition at line 104 of file objimpl.h.

_objinit_guaranteed

#define _objinit_guaranteed   _Post_equal_to_(true)

SAL annotation indicating init callback always succeeds

Use in class definitions when the init callback is guaranteed to return true.

Definition at line 99 of file objimpl.h.

objInstCreate

#define objInstCreate

(

clsname

)

(clsname*)_objInstCreate(&objClassInfoName(clsname))

ClassName *objInstCreate(ClassName)

Allocate and initialize an object instance

Allocates memory for an object instance and sets up the base ObjInst fields. The instance is returned with a reference count of 1. This function does NOT call the class's init() callback - that must be done separately via objInstInit().

Only call from factory functions!

Example usage in a factory function:

Document *documentCreate(string title) {
    Document *ret = objInstCreate(Document);
    ret->title = 0;
    strDup(&ret->title, title);
    if (!objInstInit(ret))
        goto error;
    return ret;
error:
    objRelease(&ret);
    return NULL;
}

Parameters

clsname

Class name

Returns

Newly allocated object instance (never NULL)

Definition at line 49 of file objimpl.h.

objInstInit

#define objInstInit

(

inst

)

_objInstInit(objInstBase(inst), (inst)->_clsinfo)

bool objInstInit(ClassType *inst)

Call initialization callbacks for the object's class hierarchy

Recursively calls init() callbacks starting from the root parent class down to the object's actual class. Must be called at the end of factory functions, after setting up per-instance data but before returning to the caller.

If any init() returns false, construction must abort and the factory should clean up and return NULL.

Parameters

inst	Object instance to initialize

Returns

true if all init callbacks succeeded, false if any failed

Definition at line 65 of file objimpl.h.

Function Documentation

objDefaultCmp()

intptr objDefaultCmp	(	void *	self,
		void *	other,
		uint32	flags
	)

Default comparison function for Sortable interface

Provides a generic comparison by comparing the raw bytes of object instances after the ObjInst header. First compares instance sizes, then performs memcmp on the data.

Use this as a fallback when a class implements Sortable but doesn't need custom comparison logic. For classes with pointers or complex data, implement a custom comparison function instead.

Parameters

self	First object to compare
other	Second object to compare
flags	Comparison flags (currently unused)

Returns

Negative if self < other, 0 if equal, positive if self > other

objDefaultHash()

uint32 objDefaultHash	(	void *	self,
		uint32	flags
	)

Default hash function for Hashable interface

Provides a generic hash by running MurmurHash3 over the raw bytes of the object instance after the ObjInst header.

Use this as a fallback when a class implements Hashable but doesn't need custom hash logic. For classes with pointers or complex data, implement a custom hash function instead.

Parameters

self	Object to hash
flags	Hash flags (currently unused)

Returns

32-bit hash value