OpenGATE Contents | GATE development concepts: Delegates

Problem description

Calling functions entry points from different languages has become a major challenge. Classic C function pointers are not comfortable enough to serve in high level codes like in C++. And C++ templates are too generic to be mapped back to simple C code.

Individual patch code is needed to translate function callbacks from one language layer too another for each component implementation which leads to multiple slightly different solutions for the same problem.

Solution

dotNet introduced Delegates as one defined interface to encapsulate callbacks and function or method pointers. The GATE framework takes the dotNet delegate concept as a model for its own implementation.

Definition

A gate_delegate_t instance provides storage for a native function, method and object pointer and a pointer to a dispatcher function.
The dispatcher function takes a pointer to its gate_delegate_t instance and a va_list reference that gives access to any kind of variadic function arguments.

Each kind of final delegate for a typed callback function or method is required to provide a dispatcher that translates the contents of a va_list into the native function call.

Initialization of a gate_delegate_t instance stores the native pointers to the callback function or method and/or an associated object pointer and the required dispatcher function.

When the global function gate_delegate_invoke() is called with a pointer to the initialized delegate and additional variadic arguments, it uses the delegate’s dispatcher function that extracts the variadic arguments and converts them into natively typed arguments and invokes the target function or method endpoint.

To ensure compatibility between all kinds of languages, following rules for delegate functions must be fulfilled:

1. A target function can use only primitive data types and pointers (or pointer-equivalents) as function arguments. C++ references are translated into Pointers when they are passed through delegate layers. Using whole object as by-value arguments is forbidden.
2. A target function is only allowed to return a gate_result_t type to indicate the proper execution of the function. It is a simplified kind of exception notification.
   Other kinds of status or return values need to be communicated via output-pointers as function arguments.
3. It is forbidden to raise exceptions or to initiate any other kind of asynchronous code execution from within the delegate’s target code. Exceptional conditions need to be cought through the native featureset of the used language and must be translated into a gate_result_t indicator.
4. Delegates are treated as const objects after their initialization. It is forbidden to change their contents afterwards.
5. The usage scope of a delegate is releated to the life-time of the native code it is dispatching to. Object methods are only allowed to be called as long as the target object is allocated and fully functional.
6. Delegates are weak references. They are not expected to retain objects and extend their life-time.

Implementation details

C Macros like the GATE_DELEGATE_DECLARE_ family generate a C-style callback function typedef for plain C functions and object-oriented methods including an additional this pointer.

Initialization functions like GATE_DELEGATE_INIT_FUNC and GATE_DELEGATE_INIT_OBJ help to distinguish between function and object bindings and choose the appropriate dispatcher function.

The C++ implementation uses template type deduction technologies to automatically bind a delegate to correct internal dispatcher. Therefore no additional macros are required.

C Example

 #include <gate/delegates.h>
 
 gate_result_t my_callback_function(int x, int y)
 {
   /* do something with "x" and "y" */
   return GATE_RESULT_OK;
 }
 
 GATE_DELEGATE_DECLARE_2(my_callback_delegate, int, int);

int main()
{
  gate_result_t result;
  gate_delegate_t my_delegate_instance;
  
  GATE_DELEGATE_INIT_FUNC(
    my_callback_delegate, &my_delegate_instance, 
    &my_callback_function, NULL);
  
  result = gate_delegate_invoke(&my_delegate_instance, 12, 34);
  
  return 0;
}

C++ Example

 #include <gate/delegates.hpp>
 
 class Target
 {
 public:
   void method(int x, int y)
   {
     // do something
      
  }
};

int main()
{
  Target target_instance;

  Delegate2<int, int> my_delegate_instance(
    &Target::method, &target_instance);
  
  my_delegate_instance(12 ,34);
  // equal to:
  // gate_result_t result = gate_delegate_invoke(
  //     my_delegate_instance.c_impl(), 12, 34);
  
  return 0;
}