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   MK_RT_ARGS MK_OBJ const obj, MK_CBP const __data__
	the MkObjectDeleteCallF arguments with default names
#define	MkObjectDeleteCallF_CALL   MK_RT_CALL obj, __data__
	the MkObjectDeleteCallF arguments CALL with default names
#define	MkObjectDeleteFreeF_ARGS   MK_RT_ARGS MK_CBP *dataP
	the MkObjectDeleteFreeF arguments with default names

Typedefs
typedef enum MkErrorE(*	MkObjectDeleteCallF) (MkObjectDeleteCallF_ARGS)
	static callback
typedef void(*	MkObjectDeleteFreeF) (MkObjectDeleteFreeF_ARGS)

Functions
MK_EXTERN MK_OBJ	MkObjDup_RT (MK_RT mkrt, MK_OBJ const srcobj)
	call the Dup-Constructor from the object
MK_EXTERN MK_OBJ	MkObjDup2_RT (MK_RT mkrt, MK_OBJ const srcmng, MK_STRN const ident)
	call the Dup2-Constructor from the object
MK_EXTERN MK_OBJ	MkObjMerge_RT (MK_RT mkrt, MK_OBJ const obj)
	Constructor - create a new object as a merge from an existing object
MK_EXTERN MK_OBJ	MkObjCreate_RT (MK_RT mkrt, MK_TYP type, MK_PTR nat, MK_PTR lnk)
	call the Constructor from the object
MK_EXTERN void	MkObjectDelete_RT (MK_RT mkrt, MK_OBJ obj)
	Delete-Slot - delete an instance.
MK_EXTERN void	MkObjectDispose_RT (MK_RT mkrt, MK_OBJ obj)
	Dispose-Slot - untie the connection between the Native-C-Instance and the libmkkernel-Instance.
MK_EXTERN 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 …
MK_EXTERN void	MkObjectDeleteCallbackCleanup_RT (MK_RT mkrt, MK_STRN ident)
	cleanup the DeleteCallback installed with MkObjectDeleteCallbackSetup …

MkObjectC - MkObjectC_TOR_C_API - overload
#define	MkObjCreate_NULL(...)
#define	MkObjCreate(...)
#define	MkObjCreate_2(nat, lnk)
#define	MkObjectDispose(x)
#define	MkObjectDelete(x)
#define	MkObjDup_NULL(...)
#define	MkObjDup(...)
#define	MkObjDup2_NULL(...)
#define	MkObjDup2(...)
#define	MkObjMerge_NULL(...)
#define	MkObjMerge(...)
#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 1721 of file kernel_overload_mk.h.

MkObjCreate_2

#define MkObjCreate_2	(		nat,
			lnk )

Value:

MkObjCreate(NULL,nat,lnk)

Definition at line 1722 of file kernel_overload_mk.h.

MkObjCreate_NULL

#define MkObjCreate_NULL

(

...

)

Value:

MkObjCreate_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1720 of file kernel_overload_mk.h.

MkObjDup

#define MkObjDup

(

...

)

Value:

MkObjDup_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1732 of file kernel_overload_mk.h.

MkObjDup2

#define MkObjDup2

(

...

)

Value:

MkObjDup2_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1734 of file kernel_overload_mk.h.

MkObjDup2_NULL

#define MkObjDup2_NULL

(

...

)

Value:

MkObjDup2_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1733 of file kernel_overload_mk.h.

MkObjDup_NULL

#define MkObjDup_NULL

(

...

)

Value:

MkObjDup_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1731 of file kernel_overload_mk.h.

MkObjectDelete

#define MkObjectDelete

(

x

)

Value:

MkObjectDeleteToNull(MkObjectDelete_RT,MK,x)

Definition at line 1728 of file kernel_overload_mk.h.

MkObjectDelete_1X

#define MkObjectDelete_1X

(

x

)

Value:

MkObjectDeleteToNull_X(MkObjectDelete_RT,MK,x)

Definition at line 4045 of file LibMkKernel_mk.h.

MkObjectDelete_NULL

#define MkObjectDelete_NULL

(

obj

)

Value:

MkObjectDeleteToNull(MkObjectDelete_RT,MK,obj)

Definition at line 4043 of file LibMkKernel_mk.h.

MkObjectDelete_NULL_X

#define MkObjectDelete_NULL_X

(

x

)

Value:

MkObjectDeleteToNull_X(MkObjectDelete_RT,MK,x)

Definition at line 4044 of file LibMkKernel_mk.h.

MkObjectDeleteCallbackCleanup

#define MkObjectDeleteCallbackCleanup

(

...

)

Value:

MkObjectDeleteCallbackCleanup_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1740 of file kernel_overload_mk.h.

MkObjectDeleteCallbackCleanup_NULL

#define MkObjectDeleteCallbackCleanup_NULL

(

...

)

Value:

MkObjectDeleteCallbackCleanup_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1739 of file kernel_overload_mk.h.

MkObjectDeleteCallbackSetup

#define MkObjectDeleteCallbackSetup

(

...

)

Value:

MkObjectDeleteCallbackSetup_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1742 of file kernel_overload_mk.h.

MkObjectDeleteCallbackSetup_C

#define MkObjectDeleteCallbackSetup_C

(

...

)

Value:

if (MkErrorCheckI(MkObjectDeleteCallbackSetup(__VA_ARGS__)))

Definition at line 1744 of file kernel_overload_mk.h.

MkObjectDeleteCallbackSetup_E

#define MkObjectDeleteCallbackSetup_E

(

...

)

Value:

MkErrorCheck(MkObjectDeleteCallbackSetup(__VA_ARGS__))

Definition at line 1743 of file kernel_overload_mk.h.

MkObjectDeleteCallbackSetup_NULL

#define MkObjectDeleteCallbackSetup_NULL

(

...

)

Value:

MkObjectDeleteCallbackSetup_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1741 of file kernel_overload_mk.h.

MkObjectDeleteCallF_ARGS

#define MkObjectDeleteCallF_ARGS   MK_RT_ARGS MK_OBJ const obj, MK_CBP const __data__

the MkObjectDeleteCallF arguments with default names

Definition at line 4083 of file LibMkKernel_mk.h.

MkObjectDeleteCallF_CALL

#define MkObjectDeleteCallF_CALL   MK_RT_CALL obj, __data__

the MkObjectDeleteCallF arguments CALL with default names

Definition at line 4085 of file LibMkKernel_mk.h.

MkObjectDeleteCallF_CHECK

#define MkObjectDeleteCallF_CHECK

Value:

  do { \
  assert (__data__ != NULL); \
  if (MkObjCheck(obj) == false || (*obj).self == NULL) return MK_OK; \
} while (0)

validate call to MkObjectDeleteCallF

Definition at line 4076 of file LibMkKernel_mk.h.

#define MkObjectDeleteCallF_CHECK do { \
  assert (__data__ != NULL); \
  if (MkObjCheck(obj) == false || (*obj).self == NULL) return MK_OK; \
} while (0)

MkObjectDeleteFreeF_ARGS

#define MkObjectDeleteFreeF_ARGS   MK_RT_ARGS MK_CBP *dataP

the MkObjectDeleteFreeF arguments with default names

Definition at line 4091 of file LibMkKernel_mk.h.

MkObjectDeleteToNull

#define MkObjectDeleteToNull	(		fct,
			NS,
			x )

Value:

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

Definition at line 4047 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 4048 of file LibMkKernel_mk.h.

MkObjectDispose

#define MkObjectDispose

(

x

)

Value:

MkObjectDeleteToNull(MkObjectDispose_RT,MK,x)

Definition at line 1725 of file kernel_overload_mk.h.

MkObjectDispose_1X

#define MkObjectDispose_1X

(

x

)

Value:

MkObjectDispose(MkOBJ(x))

Definition at line 4073 of file LibMkKernel_mk.h.

MkObjectDispose_NULL

#define MkObjectDispose_NULL

(

obj

)

Value:

MkObjectDeleteToNull(MkObjectDispose_RT,MK,obj)

Definition at line 4071 of file LibMkKernel_mk.h.

MkObjectDispose_NULL_X

#define MkObjectDispose_NULL_X

(

x

)

Value:

MkObjectDeleteToNull_X(MkObjectDispose_RT,MK,x)

Definition at line 4072 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 3937 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 3900 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 3945 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 3941 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 1736 of file kernel_overload_mk.h.

MkObjMerge_NULL

#define MkObjMerge_NULL

(

...

)

Value:

MkObjMerge_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 1735 of file kernel_overload_mk.h.

Typedef Documentation

MkObjectDeleteCallF

typedef enum MkErrorE( * MkObjectDeleteCallF) (MkObjectDeleteCallF_ARGS)

static callback

Definition at line 4066 of file LibMkKernel_mk.h.

MkObjectDeleteFreeF

typedef void( * MkObjectDeleteFreeF) (MkObjectDeleteFreeF_ARGS)

Definition at line 4093 of file LibMkKernel_mk.h.

Function Documentation

MkObjCreate_RT()

MK_EXTERN 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_EXTERN 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_EXTERN 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()

MK_EXTERN 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()

MK_EXTERN void MkObjectDeleteCallbackCleanup_RT	(	MK_RT	mkrt,
		MK_STRN	ident )

cleanup the DeleteCallback installed with MkObjectDeleteCallbackSetup …

See also

MkObjectDeleteCallbackSetup

MkObjectDeleteCallbackSetup_RT()

MK_EXTERN 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 !

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()

MK_EXTERN 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_EXTERN 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