MkObjectC_TOR_C_API

MkObjectC - create and destroy a managed-object … More...

Collaboration diagram for MkObjectC_TOR_C_API:

Macros
#define	MkObjInit2(rtmkV, rtExtV, sigV, typeV, refCountV, isLocalV)
	Initialize an MkObjectS.
#define	MkObjInit(rtmkV, rtExtV, cls, refCountV, isLocalV)
#define	MkObjInitFromType(typeV, isLocalV)
#define	MkObjInitFromInstance(instV)
#define	MkObjectDelete_NULL(obj)
#define	MkObjectDelete_NULL_X(x)
#define	MkObjectDelete_1X(x)
#define	MkObjectDeleteToNull(fct, NS, x)
#define	MkObjectDeleteToNull_X(fct, NS, x)
#define	MkObjectDispose_NULL(obj)
#define	MkObjectDispose_NULL_X(x)
#define	MkObjectDispose_1X(x)
#define	MkObjectDeleteCallF_CHECK
	validate call to MkObjectDeleteCallF
#define	MkObjectDeleteCallF_ARGS
	the MkObjectDeleteCallF arguments with default names
#define	MkObjectDeleteCallF_CALL   MK_RT_CALL obj, __data__
#define	MkObjectDeleteFreeF_ARGS   MK_RT_ARGS MK_CBP *dataP __parser__(inout)
	the MkObjectDeleteFreeF arguments with default names

Typedefs
typedef enum MkErrorE(*	MkObjectDeleteCallF) (MK_RT mkrt, MK_OBJN const obj, MK_STRN const typeName, MK_HDL const typeHdl, MK_HDL const objHdl, MK_CBP const __data__)
	static callback to delete an obj …
typedef void(*	MkObjectDeleteFreeF) (MkObjectDeleteFreeF_ARGS)

Functions
MK_OBJ	MkObjDup_RT (MK_RT mkrt, MK_OBJ const srcobj)
	call the Dup-Constructor from the object
MK_OBJ	MkObjDup2_RT (MK_RT mkrt, MK_OBJ const srcmng, MK_STRN const ident)
	call the Dup2-Constructor from the object
MK_OBJ	MkObjMerge_RT (MK_RT mkrt, MK_OBJ const obj)
	Constructor - create a new object as a merge from an existing object
MK_OBJ	MkObjCreate_RT (MK_RT mkrt, MK_TYP type, MK_PTR nat, MK_PTR lnk)
	call the Constructor from the object
void	MkObjectDelete_RT (MK_RT mkrt, MK_OBJ obj)
	Delete-Slot - delete an instance.
void	MkObjectDispose_RT (MK_RT mkrt, MK_OBJ obj)
	Dispose-Slot - untie the connection between the Native-C-Instance and the libmkkernel-Instance.
enum MkErrorE	MkObjectDeleteCallbackSetup_RT (MK_RT mkrt, MK_STRN ident, MkObjectDeleteCallF fCall, MK_CBP callback, MkObjectDeleteFreeF fFree, MK_STRN filter)
	Create/Delete the instance-delete-callback …
void	MkObjectDeleteCallbackCleanup_RT (MK_RT mkrt, MK_STRN ident)
	cleanup the DeleteCallback installed with MkObjectDeleteCallbackSetup …

MkObjectC - MkObjectC_TOR_C_API - overload
#define	MkObjDup_NULL(...)
#define	MkObjDup(...)
#define	MkObjMerge_NULL(...)
#define	MkObjMerge(...)
#define	MkObjCreate_NULL(...)
#define	MkObjCreate(...)
#define	MkObjCreate_2(nat, lnk)
#define	MkObjectDispose(x)
#define	MkObjectDelete(x)
#define	MkObjDup2_NULL(...)
#define	MkObjDup2(...)
#define	MkObjectDeleteCallbackCleanup_NULL(...)
#define	MkObjectDeleteCallbackCleanup(...)
#define	MkObjectDeleteCallbackSetup_NULL(...)
#define	MkObjectDeleteCallbackSetup(...)
#define	MkObjectDeleteCallbackSetup_E(...)
#define	MkObjectDeleteCallbackSetup_C(...)

Detailed Description

MkObjectC - create and destroy a managed-object …

Macro Definition Documentation

MkObjCreate

#define MkObjCreate

(

...

)

Value:

MkObjCreate_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1760 of file kernel_overload_mk.h.

MkObjCreate_2

#define MkObjCreate_2	(		nat,
			lnk )

Value:

MkObjCreate(NULL,nat,lnk)

Definition at line 1761 of file kernel_overload_mk.h.

MkObjCreate_NULL

#define MkObjCreate_NULL

(

...

)

Value:

MkObjCreate_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1759 of file kernel_overload_mk.h.

MkObjDup

#define MkObjDup

(

...

)

Value:

MkObjDup_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1754 of file kernel_overload_mk.h.

MkObjDup2

#define MkObjDup2

(

...

)

Value:

MkObjDup2_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1771 of file kernel_overload_mk.h.

MkObjDup2_NULL

#define MkObjDup2_NULL

(

...

)

Value:

MkObjDup2_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1770 of file kernel_overload_mk.h.

MkObjDup_NULL

#define MkObjDup_NULL

(

...

)

Value:

MkObjDup_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1753 of file kernel_overload_mk.h.

MkObjectDelete

#define MkObjectDelete

(

x

)

Value:

MkObjectDeleteToNull(MkObjectDelete_RT,MK,x)

Definition at line 1767 of file kernel_overload_mk.h.

MkObjectDelete_1X

#define MkObjectDelete_1X

(

x

)

Value:

MkObjectDeleteToNull_X(MkObjectDelete_RT,MK,x)

Definition at line 4186 of file LibMkKernel_mk.h.

MkObjectDelete_NULL

#define MkObjectDelete_NULL

(

obj

)

Value:

MkObjectDeleteToNull(MkObjectDelete_RT,MK,obj)

Definition at line 4184 of file LibMkKernel_mk.h.

MkObjectDelete_NULL_X

#define MkObjectDelete_NULL_X

(

x

)

Value:

MkObjectDeleteToNull_X(MkObjectDelete_RT,MK,x)

Definition at line 4185 of file LibMkKernel_mk.h.

MkObjectDeleteCallbackCleanup

#define MkObjectDeleteCallbackCleanup

(

...

)

Value:

MkObjectDeleteCallbackCleanup_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1775 of file kernel_overload_mk.h.

MkObjectDeleteCallbackCleanup_NULL

#define MkObjectDeleteCallbackCleanup_NULL

(

...

)

Value:

MkObjectDeleteCallbackCleanup_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1774 of file kernel_overload_mk.h.

MkObjectDeleteCallbackSetup

#define MkObjectDeleteCallbackSetup

(

...

)

Value:

MkObjectDeleteCallbackSetup_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1777 of file kernel_overload_mk.h.

MkObjectDeleteCallbackSetup_C

#define MkObjectDeleteCallbackSetup_C

(

...

)

Value:

if (MkErrorCheckI(MkObjectDeleteCallbackSetup(__VA_ARGS__)))

Definition at line 1779 of file kernel_overload_mk.h.

MkObjectDeleteCallbackSetup_E

#define MkObjectDeleteCallbackSetup_E

(

...

)

Value:

MkErrorCheck(MkObjectDeleteCallbackSetup(__VA_ARGS__))

Definition at line 1778 of file kernel_overload_mk.h.

MkObjectDeleteCallbackSetup_NULL

#define MkObjectDeleteCallbackSetup_NULL

(

...

)

Value:

MkObjectDeleteCallbackSetup_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1776 of file kernel_overload_mk.h.

MkObjectDeleteCallF_ARGS

#define MkObjectDeleteCallF_ARGS

Value:

  MK_RT_ARGS                                 \
  MK_OBJN const obj __parser__(internal),    \
  MK_STRN const typeName,                    \
  MK_HDL  const typeHdl,                     \
  MK_HDL  const objHdl,                      \
  MK_CBP  const __data__                     \

the MkObjectDeleteCallF arguments with default names

Definition at line 4223 of file LibMkKernel_mk.h.

#define MkObjectDeleteCallF_ARGS             \
  MK_RT_ARGS                                 \
  MK_OBJN const obj __parser__(internal),    \
  MK_STRN const typeName,                    \
  MK_HDL  const typeHdl,                     \
  MK_HDL  const objHdl,                      \
  MK_CBP  const __data__                     \
 

MkObjectDeleteCallF_CALL

#define MkObjectDeleteCallF_CALL   MK_RT_CALL obj, __data__

Definition at line 4231 of file LibMkKernel_mk.h.

MkObjectDeleteCallF_CHECK

#define MkObjectDeleteCallF_CHECK

Value:

  do { \
  assert (__data__ != NULL); \
} while (0)

validate call to MkObjectDeleteCallF

Definition at line 4217 of file LibMkKernel_mk.h.

#define MkObjectDeleteCallF_CHECK do { \
  assert (__data__ != NULL); \
} while (0)

MkObjectDeleteFreeF_ARGS

#define MkObjectDeleteFreeF_ARGS   MK_RT_ARGS MK_CBP *dataP __parser__(inout)

the MkObjectDeleteFreeF arguments with default names

Definition at line 4281 of file LibMkKernel_mk.h.

MkObjectDeleteToNull

#define MkObjectDeleteToNull	(		fct,
			NS,
			x )

Value:

if (x) { fct (NS##_RT_CALL x);        (x) = NULL ; }

Definition at line 4188 of file LibMkKernel_mk.h.

MkObjectDeleteToNull_X

#define MkObjectDeleteToNull_X	(		fct,
			NS,
			x )

Value:

if (x) { fct (NS##_RT_CALL MkOBJ(x)); (x) = NULL ; }

Definition at line 4189 of file LibMkKernel_mk.h.

MkObjectDispose

#define MkObjectDispose

(

x

)

Value:

MkObjectDeleteToNull(MkObjectDispose_RT,MK,x)

Definition at line 1764 of file kernel_overload_mk.h.

MkObjectDispose_1X

#define MkObjectDispose_1X

(

x

)

Value:

MkObjectDispose(MkOBJ(x))

Definition at line 4214 of file LibMkKernel_mk.h.

MkObjectDispose_NULL

#define MkObjectDispose_NULL

(

obj

)

Value:

MkObjectDeleteToNull(MkObjectDispose_RT,MK,obj)

Definition at line 4212 of file LibMkKernel_mk.h.

MkObjectDispose_NULL_X

#define MkObjectDispose_NULL_X

(

x

)

Value:

MkObjectDeleteToNull_X(MkObjectDispose_RT,MK,x)

Definition at line 4213 of file LibMkKernel_mk.h.

MkObjInit

#define MkObjInit	(		rtmkV,
			rtExtV,
			cls,
			refCountV,
			isLocalV )

Value:

  MkObjInit2(rtmkV,rtExtV,cls##_SIGNATURE,cls##_TT,refCountV,isLocalV)

Definition at line 4076 of file LibMkKernel_mk.h.

#define MkObjInit(rtmkV,rtExtV,cls,refCountV,isLocalV) \
  MkObjInit2(rtmkV,rtExtV,cls##_SIGNATURE,cls##_TT,refCountV,isLocalV)

MkObjInit2

#define MkObjInit2	(		rtmkV,
			rtExtV,
			sigV,
			typeV,
			refCountV,
			isLocalV )

Value:

    (struct MkObjectS) {                                            \
      .signature    = sigV,                                         \
      .refCount     = refCountV,                                    \
      .self         = NULL,                                         \
      .type         = typeV,                                        \
      .env          = NULL,                                         \
      .selfCreated  = false,                                        \
      .selfRefCount = 0,                                            \
      .objRt        = rtmkV,                                        \
      .objRtExt     = rtExtV,                                       \
      .obj_protect  = {                                             \
        .isLocal      = isLocalV,                                   \
        .prev         = NULL,                                       \
        .next         = NULL,                                       \
      },                                                            \
    }

Initialize an MkObjectS.

This is internal code used in the CTOR toinitialize the memory after the new object was created.

#define MkDumpObjInit MkObjInit(MkDump, 0, false)
...

Attention

with .obj_protect.isLocal=true the MkSelfDeleteForce_RT will NOT delete the memory

Definition at line 4039 of file LibMkKernel_mk.h.

  #define MkObjInit2(rtmkV,rtExtV,sigV,typeV,refCountV,isLocalV)    \
    (struct MkObjectS) {                                            \
      .signature    = sigV,                                         \
      .refCount     = refCountV,                                    \
      .self         = NULL,                                         \
      .type         = typeV,                                        \
      .env          = NULL,                                         \
      .selfCreated  = false,                                        \
      .selfRefCount = 0,                                            \
      .objRt        = rtmkV,                                        \
      .objRtExt     = rtExtV,                                       \
      .obj_protect  = {                                             \
        .isLocal      = isLocalV,                                   \
        .prev         = NULL,                                       \
        .next         = NULL,                                       \
      },                                                            \
    }

MkObjInitFromInstance

#define MkObjInitFromInstance

(

instV

)

Value:

  MkObjInit2(MK_RT_PTR, NULL, MkOBJ_R(instV).type->objsig, MkOBJ_R(instV).type,  0, false)

Definition at line 4084 of file LibMkKernel_mk.h.

#define MkObjInitFromInstance(instV) \
  MkObjInit2(MK_RT_PTR, NULL, MkOBJ_R(instV).type->objsig, MkOBJ_R(instV).type,  0, false)

MkObjInitFromType

#define MkObjInitFromType	(		typeV,
			isLocalV )

Value:

  MkObjInit2(MK_RT_PTR, NULL, (*typeV).objsig, typeV,  0, isLocalV)

Definition at line 4080 of file LibMkKernel_mk.h.

#define MkObjInitFromType(typeV,isLocalV) \
  MkObjInit2(MK_RT_PTR, NULL, (*typeV).objsig, typeV,  0, isLocalV)

MkObjMerge

#define MkObjMerge

(

...

)

Value:

MkObjMerge_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1756 of file kernel_overload_mk.h.

MkObjMerge_NULL

#define MkObjMerge_NULL

(

...

)

Value:

MkObjMerge_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1755 of file kernel_overload_mk.h.

Typedef Documentation

MkObjectDeleteCallF

typedef enum MkErrorE( * MkObjectDeleteCallF) (MK_RT mkrt,MK_OBJN const obj, MK_STRN const typeName, MK_HDL const typeHdl, MK_HDL const objHdl, MK_CBP const __data__)

static callback to delete an obj …

This callback is called when the obj is deleted. Setting up the callback is done using the MkObjectDeleteCallbackSetup function.

Introduction

Deleting an obj is not easy because there are generally two parts, the Target-Programming-Language (TPL) part and the Programming-Language-Micro-Kernel (PLMK) part.

Generally, two callbacks are involved:

• The C-callback runs under the control of the PLMK
• The TPL-callback runs under the control of the TPL. (non C language)

Definition

The obj is defined by the three callback arguments typeName, typeHdl and objHdl.

• The objHdl is important because this is the export handle used as a reference to the internal object.
• In Remote-Procedure-Call (RPC), this export handle is used to link the client object to the server object, and when the server object is deleted, the client object must also be deleted.

Workflow

This callback is called in MkRefDecrWithoutSelf and MkRefDecrWithUnlinkSelf, immediately before the PLMK-part is deleted and generally (not always) after the TPL-part is deleted.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the theKernel part of the object, only use internal in the C-callback
[in]	typeName	the return from MkObjectToNameOfType
[in]	typeHdl	the return from MkObjectHandleGetOfType
[in]	objHdl	the return from MkObjectHandleGet

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Attention

It is a design flaw to use obj in the TPL-callback because using obj or using the MkObjectHandleResolve function on objHdl will recreate the already deleted TPL-object and this generally breaks the TPL-runtime.

Just think of a Garbage-Collection (GC) deleting an object and that object is reborn in the GC deletion process.

Note

In the Target-Programming-Language (TPL) the TPL-callback is only called if the obj has a MkObjectS::self pointer.

Definition at line 4207 of file LibMkKernel_mk.h.

MkObjectDeleteFreeF

typedef void( * MkObjectDeleteFreeF) (MkObjectDeleteFreeF_ARGS)

Definition at line 4284 of file LibMkKernel_mk.h.

Function Documentation

MkObjCreate_RT()

MK_OBJ MkObjCreate_RT	(	MK_RT	mkrt,
		MK_TYP	type,
		MK_PTR	nat,
		MK_PTR	lnk )

call the Constructor from the object

Create a new object using type and an additional nat. This requie a MkTypeS::constructor be available

Attention

the type have to be resolved fist, already done in MkObjCreate->MkTypeResolve

MkObjDup2_RT()

MK_OBJ MkObjDup2_RT	(	MK_RT	mkrt,
		MK_OBJ const	srcmng,
		MK_STRN const	ident )

call the Dup2-Constructor from the object

The Dup2-Constructor create a new object-shell, and copy all the internal data from the srcobj to the newobj. An additional ident is used to set e name ressource After the Dup2-Constructor the srcobj is unchanged.

Returns

the new object or MK_NULL if no Dup2-Constructor fails

See also

MkObjMerge MkObjReset MkTypeDup2

MkObjDup_RT()

MK_OBJ MkObjDup_RT	(	MK_RT	mkrt,
		MK_OBJ const	srcobj )

call the Dup-Constructor from the object

This is an Instance-Callback the real Dup function called depend on the MkObjectS::type.

• currently supported: ErrorDup, BufferDup, BufferStreamDup, BufferListDup

The Dup-Constructor create a new object-shell, and copy all the internal data from the srcobj to the newobj. After the Dup-Constructor the srcobj is unchanged.

The new instance belongs to the caller and may have to be released if necessary. A manual release using ObjectDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkObjectC instance, the instance is owned by the caller

See also

MkObjMerge_RT MkObjReset_RT

MkObjectDelete_RT()

void MkObjectDelete_RT	(	MK_RT	mkrt,
		MK_OBJ	obj )

Delete-Slot - delete an instance.

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. The internal memory will be freed and the object-pointer will be set to NULL. If the object-pointer is already NULL nothing will be done.
2. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
3. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
4. After a SOFT-delete, the outher shell is still alive, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.
5. On HARD-delete read more at MkSelfDeleteForce

MkObjectDeleteCallbackCleanup_RT()

void MkObjectDeleteCallbackCleanup_RT	(	MK_RT	mkrt,
		MK_STRN	ident )

cleanup the DeleteCallback installed with MkObjectDeleteCallbackSetup …

See also

MkObjectDeleteCallbackSetup

MkObjectDeleteCallbackSetup_RT()

enum MkErrorE MkObjectDeleteCallbackSetup_RT	(	MK_RT	mkrt,
		MK_STRN	ident,
		MkObjectDeleteCallF	fCall,
		MK_CBP	callback,
		MkObjectDeleteFreeF	fFree,
		MK_STRN	filter )

Create/Delete the instance-delete-callback …

The callback is called shortly before deleting an instance and is used to synchronize object management across the network.

The ident identifies the callback

• before a new callback is created the existing-callback with name ident is deleted.
• The ident is also required to delete the callback.
• If the special ident ALL is used than all callbacks are deleted first.

The fCall (C-Only) or callback (Non-C) it is the callback called

• If MK_NULL than the callback with name ident is deleted if exists and no new callback is created.
• If MK_NULL then it is identical to MkObjectDeleteCallbackCleanup(ident).

The filter is a POSIX Extended Regular Expression to filter on type-names.

• The filter is optional and is only used if not MK_NULL and not "":
• The filter is applied to MkTypeS::type_name like MkBufferC.
• The POSIX Extended Regular Expression syntax is defined in man 7 regex.
• If the filter is not used, the fCall is called on every instance deletion !

C-callback definition details:

Read more at MkObjectDeleteCallF

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ident	Identify the callback, have to ne non MK_NULL and not "".
[in]	fCall	(C-Only) Internal required: the callback, if MK_NULL than the callback is deleted.
[in]	callback	Optional: the parameter for fcall, for cleanup use fFree.
[in]	fFree	(C-Only) Internal optional: cleanup callback data
[in]	filter	Optional: is an regular expression to filter for MkTypeS::type_name.

See also

MkObjectDeleteCallbackCleanup

MkObjectDeleteCallbackSetup : callback signature

Read more at: Callback signature

MkObjectDeleteCallbackSetup : callback example

Read more at: Callback example

MkObjectDispose_RT()

void MkObjectDispose_RT	(	MK_RT	mkrt,
		MK_OBJ	obj )

Dispose-Slot - untie the connection between the Native-C-Instance and the libmkkernel-Instance.

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
2. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
3. After a SOFT-delete, the outher shell is still active, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.

MkObjMerge_RT()

MK_OBJ MkObjMerge_RT	(	MK_RT	mkrt,
		MK_OBJ const	obj )

Constructor - create a new object as a merge from an existing object

The Merge-Constructor create a new object-shell, and take-over all the internal data from the source-object. After the Merge-Constructor the source-object is empty as if a object-reset was called.

One usage of the Merge-Constructor is to get a lightweight-copy of a Thread-Local-Storage object for external usage.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	The source-object of the merge.

Returns

The new object or MK_NULL if no Merge-Constructor is available

Attention

The new object have to be deleted.

See also

MkObjDup_RT MkObjReset_RT MkObjectDelete