MkKernel_Parser_Callback_C_API

callback : define the __parser__ attribute related to the callback integration … More...

Collaboration diagram for MkKernel_Parser_Callback_C_API:

Macros
#define	__parser__callback_name   callback-name=PREFIX
	prefix of the callback-identifer …
#define	__parser__callback_data   callback-data
	define the data-attribute of the callback-call …
#define	__parser__callback_call   callback-call
	define the function-pointer to call as callback …
#define	__parser__callback_free   callback-free
	define the function-pointer to free the callback-data …
#define	__parser__callback_copy   callback-copy
	define the function-pointer to copy the callback-data …
#define	__parser__callback_once   callback-once
	is the callback only used once ?
#define	__parser__callback_null   callback-null
	is the null value allowed for the callback ?

Detailed Description

callback : define the __parser__ attribute related to the callback integration …

A callback is a piece of code calling back from the C-API into the Target-Programming-Language (TPL) .

• Note: the __parser__ technologie is defined at: alc parser

The callback is generally defined as a C function with :

FUNCTION ( ... , callback-call, callback-data, ?callback-free?, ?callback-copy?, ... )

DEFINITION

The attribute __parser__(callback-name) define the namespace of the callback-identifer :

attribute	position	name	example
__parser__(callback-name)	prefix	Xxxx	MyCallback
__parser__(callback-call)	postfix	Call	MyCallbackCall
__parser__(callback-free)	postfix	Free	MyCallbackFree
__parser__(callback-copy)	postfix	Copy	MyCallbackCopy

A callback is defined on FUNCTION level :

what	required?	definition
__parser__(callback-name)	yes	prefix of the callback-identifer …
__parser__(callback-null)	no	is the null value allowed for the callback ?
__parser__(callback-once)	no	is the callback only used once ?

Definition

scope	global or function
usage	__parser__global__(FUNCTION:callback-WHAT?=VALUE?
usage	__parser__(callback-WHAT?=VALUE?) FUNCTION ...)

and the callback is defined on ARGUMENT level :

what	required?	definition
__parser__(callback-call)	yes	define the function-pointer to call as callback …
__parser__(callback-data)	yes	define the data-attribute of the callback-call …
__parser__(callback-free)	no	define the function-pointer to free the callback-data …
__parser__(callback-copy)	no	define the function-pointer to copy the callback-data …

Definition

scope	global or function
usage	__parser__global__(FUNCTION:ARGUMENT:callback-WHAT
usage	FUNCTION ( type ARGUMENT __parser__(callback-WHAT) ...)

USAGE

The meta-code-external-header-file (META-HEADER) from file sqlite3.h :

• SQLITE_API int sqlite3_exec(
    sqlite3*,                                  /* An open database */
    const char *sql,                           /* SQL to be evaluated */
    int (*callback)(void*,int,char**,char**),  /* Callback function */
    void *,                                    /* 1st argument to callback */
    char **errmsg                              /* Error msg written here */
  );

The meta-code-header-wrapper-file (META-WRAPPER) from file theSq3Lite/c/sqlite3_sq3.h :

• // define the callback
  __parser__global__(sqlite3_exec:callback-name=LiteExec);
  __parser__global__(sqlite3_exec:callback-null=yes);
  __parser__global__(sqlite3_exec:callback-once=yes);
  __parser__global__(sqlite3_exec:callback_call:callback-call=yes);
  __parser__global__(sqlite3_exec:callback_data:callback-data=yes);
   
  // callback-call argument name is "callback_call"
  __parser__global__(sqlite3_exec:2:arg-name=callback_call);
   
  // callback-data argument name is "callback_data"
  __parser__global__(sqlite3_exec:3:arg-name=callback_data);
   
  // SPECIAL: the double index (2:0...) is applied to the inner "callback" function type of "sqlite3_exec"
  __parser__global__(sqlite3_exec:2:0:arg-name=callV1); // attention name of the INDEX=0 argument in TYPE
  __parser__global__(sqlite3_exec:2:0:arg-type=MK_CBP);
  __parser__global__(sqlite3_exec:2:1:arg-name=num);
  __parser__global__(sqlite3_exec:2:2:arg-name=vals);
  __parser__global__(sqlite3_exec:2:2:array=yes);
  __parser__global__(sqlite3_exec:2:3:arg-name=cols);
  __parser__global__(sqlite3_exec:2:3:array=yes);
   
  __parser__global__(sqlite3_exec:errmsg:internal=yes);
  __parser__global__(sqlite3_exec:errmsg:default=NULL);

The All-Language-Compiler (ALC) configuration for Python from theSq3Lite/py/compiler.tcl :

• The callback-identifer is used to lookup the real-callback-name in der identifier-database of the Target-Programming-Language (TPL).
• The identifier-database is usually defined at : MyPackage/MyLanguage/compiler.tcl
• The identifier-database is usually defined as array with name : map_M2S_local
  • Example:

    array set map_M2S_local {
     
        LiteExecCall    NS(LiteExecCall)
        LiteExecV2Call  NS(LiteExecV2Call)
    }

• The real callback-name is the value behind the callback-identifer
  • Example: callback-name=LiteExec → callback-call=LiteExeCallc → callback="NS(LiteExecCall)"
• The NS ia a macro used to give the Python api a unique binary-namespace
  • Eyample: #define NS(n) pysq3lite_ ## n

The generated code for the Python api at file theSq3Lite/tcl/Sq3LiteC_py.c :

• static OT_ProcRet NS(Sq3LiteC_Exec) (Sq3LiteC_ARGS) {
    OT_SETUP_hdl;
    OT_SETUP_VARARGS(1,2,Exec_doc);
    MK_STRN sql = 0;
    OT_CHECK_REQUIRED(OT_CHECK_STRN (sql))
    OT_SETUP_CALLABLE_ONCE(callback_data)
    OT_CHECK_OPTIONAL(OT_CHECK_CALLABLE(callback_data))
    OT_CHECK_NOARGS;
    Sq3Fupu_Sq3LiteExec_callback_call callback_call = (callback_data == NULL ? NULL : NS(LiteExecCall));
    MkErrorC_Check(hdl,Sq3LiteExec (hdl, sql, callback_call, callback_data));
    OT_retObj_SET_None;
    goto end;
    error:
    OT_retObj_SET_Error;
    end:
    OT_CLEANUP_CALLABLE_ONCE(callback_data)
    OT_retObj_RETURN;
  }

The callback-call is defined by the All-Language-Compiler (ALC) :

•     #define Sq3Fupu_Sq3LiteExec_callback_call_ret  MK_I32
      #define Sq3Fupu_Sq3LiteExec_callback_call_args MK_CBP callV1, MK_I32 num, MK_STR *vals, MK_STR *cols
      typedef Sq3Fupu_Sq3LiteExec_callback_call_ret (*Sq3Fupu_Sq3LiteExec_callback_call) (Sq3Fupu_Sq3LiteExec_callback_call_args);

The callback-call is designed by the programmer :

• Sq3Fupu_Sq3LiteExec_callback_call_ret NS(LiteExecCall) ( Sq3Fupu_Sq3LiteExec_callback_call_args )
  {
    Sq3Fupu_Sq3LiteExec_callback_call_check;
   
    // 1. setup environment
    if (_Py_IsFinalizing()) return 1;
    Sq3Fupu_Sq3LiteExec_callback_call_ret ret=0;
   
    MkCallS *cbS = callV1;
    MkRtSetup_RT(cbS->mkrt);
   
    OT_OBJ_T resultO = NULL;
    OT_OBJ_T valsO = PyList_New(num);
    OT_OBJ_T colsO = PyList_New(num);
    for (int i=0; i<num; i++) {
      check_LNG(PyList_SetItem(valsO,i,STRN2VAL(vals[i]))) goto error_lng;
    }
    for (int i=0; i<num; i++) {
      check_LNG(PyList_SetItem(colsO,i,STRN2VAL(cols[i]))) goto error_lng;
    }
   
    PyErr_Clear();
   
    // call the function
    resultO = PyObject_CallFunctionObjArgs(cbS->callable, valsO, colsO, NULL);
   
    if (resultO == NULL) {
      goto error_lng;
    }
   
  end:
    Py_CLEAR(valsO);
    Py_CLEAR(colsO);
    Py_CLEAR(resultO);
    return ret;
  error_lng:
    OT_ERROR_LNG_2_META(cbS->hdl);
  error_mq: MK_UNUSED
    MkErrorStack_0E();
  error_end: MK_UNUSED
    ret=1;
    goto end;
  }

Macro Definition Documentation

__parser__callback_call

#define __parser__callback_call   callback-call

define the function-pointer to call as callback …

See also

MkKernel_Parser_Callback_C_API

Definition at line 1936 of file parser_mk.h.

__parser__callback_copy

#define __parser__callback_copy   callback-copy

define the function-pointer to copy the callback-data …

See also

MkKernel_Parser_Callback_C_API

Definition at line 1946 of file parser_mk.h.

__parser__callback_data

#define __parser__callback_data   callback-data

define the data-attribute of the callback-call …

See also

MkKernel_Parser_Callback_C_API

Definition at line 1931 of file parser_mk.h.

__parser__callback_free

#define __parser__callback_free   callback-free

define the function-pointer to free the callback-data …

See also

MkKernel_Parser_Callback_C_API

Definition at line 1941 of file parser_mk.h.

__parser__callback_name

#define __parser__callback_name   callback-name=PREFIX

prefix of the callback-identifer …

See also

MkKernel_Parser_Callback_C_API

Definition at line 1926 of file parser_mk.h.

__parser__callback_null

#define __parser__callback_null   callback-null

is the null value allowed for the callback ?

A NULL value is often require to disable or reset the callback.

See also

MkKernel_Parser_Callback_C_API

Example

code from file theConfig/c/LcConfigC_lc.h

__parser__(callback-name=ConfigInclude, callback-null)
LC_EXTERN enum MkErrorE MK_DECL LcConfigSetIncludeFunc_RT ( 
  MK_PARSER_RT
  LC_CFG const          cfg, 
  LcConfigIncludeCallF  fConfigIncludeCall  __parser__(callback-call) ,
  LC_CBP                fConfigIncludeData  __parser__(callback-data) ,
  LcConfigIncludeFreeF  fConfigIncludeFree  __parser__(callback-free)
) MK_ATTR_RT_INSTANCE;

Definition at line 1962 of file parser_mk.h.

__parser__callback_once

#define __parser__callback_once   callback-once

is the callback only used once ?

See also

MkKernel_Parser_Callback_C_API

Definition at line 1951 of file parser_mk.h.