Macros

Macros for the creation/deletion and casting of objects of all types as well as some miscellaneous macros to get the base object, base class and reference count of objects.

Summary

S_NEW	Create a new object of the given object type.
S_NEW_FROM_NAME	Create a new object of the given object type name.
S_DELETE	Delete an object.
S_FORCE_DELETE	Force deletion of an object.
S_CAST_SAFE	Safe cast the given object to the given type.
S_CAST_UNSAFE	Unsafe cast the given object to the given type.
S_CAST	Cast the given object to the given type.
S_OBJECT_CALL	Call the given function method of the given SObject.
S_OBJECT_METH_VALID	Test if the given function method of the given SObject can be called.
S_OBJECT	Return the given object as a base object.
S_OBJECT_REF	Get the given object’s reference count.
S_OBJECT_CLS	Get the given object’s base class.
S_OBJECTCLASS	Get the given class’s base class.
S_FIND_CLASS	Get the given object type class.

New/Delete

macro S_NEW(OBJTYPE, ERROR)

Create a new object of the given object type.

Also initializes the object members and inherited members. For example:

 SMapList *myMapList = S_NEW(SMapList, error);

Parameters:

• OBJTYPE –

  Object type to create.

• ERROR –

  Error code (of type s_erc*).

Return:

Pointer to the newly created object (of type OBJTYPE*).

See also:

S_NEW_FROM_NAME

macro S_NEW_FROM_NAME(OBJTYPE_NAME, ERROR)

Create a new object of the given object type name.

Also initializes the object members and inherited members. For example:

 SMapList *myMapList = (SMapList*)S_NEW("SMapList", error);

Parameters:

• OBJTYPE_NAME –

  String of the type of the object to create.

• ERROR –

  Error code (of type s_erc*).

Return:

Pointer to the newly created object (of type SObject*).

See also:

S_NEW

macro S_DELETE(SELF, FUNC_NAME, ERROR)

Delete an object.

The delete macro works in two stages, first a call is made to the dispose method of SObjectClass, then if the object is no longer referenced, a call is made to the destroy method of SObjectClass. The given object pointer, SELF, is set to NULL, regardless of whether the object was deleted or not.

This allows full control over the reference counting of an object. For most normal objects the dispose method of SObjectClass would look like the SString dispose function in engine/src/base/objsystem/primitives.c:

 static void DisposeString(void *obj, s_erc *error)
 {
     S_CLR_ERR(error);
     SObjectDecRef(S_OBJECT(obj));
 }

But, if the situation arises that an object should not be deleted, by users or other objects (for example read data), then one sets the dispose method of SObjectClass of that object’s class to NULL in the object class initialization and also an SObjectIncRef statement to the init method of SObjectClass of that object. Therefore, when the object is initialized it’s reference counter is increased, and when S_DELETE is called it does not get decreased by the dispose method of SObjectClass, and not deleted. The object would then have to be deleted by a call to S_FORCE_DELETE.

Parameters:

• SELF –

  Pointer to the object to delete.

• FUNC_NAME –

  The current function name (optional, can be NULL, used for logging if an error occurred).

• ERROR –

  Error code (of type s_erc*).

macro S_FORCE_DELETE(SELF, FUNC_NAME, ERROR)

Force deletion of an object.

The object is deleted, with a call to the destroy method of SObjectClass to free up the object resources, regardless of whether it is referenced or not. The pointer to the object will point to NULL after this operation.

Parameters:

• SELF –

  Pointer to the object to delete.

• FUNC_NAME –

  The current function name (optional, can be NULL, used for logging if an error occurred).

• ERROR –

  Error code (of type s_erc*).

See also:

S_DELETE

Cast

macro S_CAST_SAFE(OBJECT, OBJTYPE, ERROR)

Safe cast the given object to the given type.

Parameters:

• OBJECT –

  Pointer to the object to cast.

• OBJTYPE –

  The type of the object to cast the given object to.

• ERROR –

  Error code (of type s_erc*).

Return:

Pointer to Object casted to OBJTYPE, or NULL on error.

macro S_CAST_UNSAFE(OBJECT, OBJTYPE)

Unsafe cast the given object to the given type.

This cast is unsafe (but faster than S_CAST_SAFE), and should only be used when you are sure of the object types.

Parameters:

• OBJECT –

  Pointer to the object to cast.

• OBJTYPE –

  The type of the object to cast the given object to.

Return:

Pointer to Object casted to OBJTYPE.

macro S_CAST(OBJECT, OBJTYPE, ERROR)

Cast the given object to the given type.

This cast reverts to either S_CAST_SAFE or S_CAST_UNSAFE, depending on the build time definition of SPCT_DO_SAFE_CAST.

Parameters:

• OBJECT –

  Pointer to the object to cast.

• OBJTYPE –

  The type of the object to cast the given object to.

• ERROR –

  Error code (of type s_erc*).

Return:

Pointer to Object casted to OBJTYPE.

See also SPCT_DO_SAFE_CAST

Function Methods

macro S_OBJECT_CALL(SELF, FUNC)

Call the given function method of the given SObject.

Parameters:

• SELF –

  The given SObject*.

• FUNC –

  The function method of the given object to call.

Note:

This casting is not safety checked.

Example usage:

 S_OBJECT_CALL(self, func)(param1, param2, ..., paramN);

where param1, param2, ..., paramN are the parameters passed to the object function func.

macro S_OBJECT_METH_VALID(SELF, FUNC)

Test if the given function method of the given SObject can be called.

Parameters:

• SELF –

  The given SObject*.

• FUNC –

  The function method of the given object to check.

Return:

TRUE if function can be called, otherwise FALSE.

Note:

This casting is not safety checked.

macro S_OBJECT(SELF)

Return the given object as a base object.

Parameters:

• SELF –

  The given object.

Return:

Given object as SObject* type.

Note:

This casting is not safety checked.

Reference

macro S_OBJECT_REF(SELF)

Get the given object’s reference count.

Parameters:

• SELF –

  The given object.

Return:

Constant uint32 reference count of the given object.

Note:

This casting is not safety checked.

Class

macro S_OBJECT_CLS(SELF)

Get the given object’s base class.

Parameters:

• SELF –

  The given object.

Return:

Pointer to the SObjectClass class of the given object.

Note:

This casting is not safety checked.

macro S_OBJECTCLASS(SELF)

Get the given class’s base class.

Parameters:

• SELF –

  The given class.

Return:

Pointer to the SObjectClass class of the given class.

Note:

This casting is not safety checked.

macro S_FIND_CLASS(OBJTYPE, ERROR)

Get the given object type class.

Parameters:

• OBJTYPE –

  Object type to find the class of.

• ERROR –

  Error code (of type s_erc*).

Return:

Pointer to the class of object type (of type OBJTYPECLASS*).