Table Of Contents

Previous topic

SObject Primitives

Next topic

Simple Containers

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*).