Copyright (c) 2009 Sun Microsystems, Inc.

How to create a new service
^^^^^^^^^^^^^^^^^^^^^^^^^^^

A "service" is a set of C functions in a structure that a
service dynamic linker uses when a dynamic plugin is loaded.

If you want to export C++ class you need to provide an
extern "C" function that will create a new instance of your class,
and put it in a service.

Data structures are not part of the service structure, but they are part
of the API you create and usually need to be declared in the same
service_*.h file.

To turn a set of functions (foo_func1, foo_func2)
into a service "foo" you need to

1. create a new file include/mysql/service_foo.h

2. the template is
==================================================================
  #ifndef MYSQL_SERVICE_FOO_INCLUDED
  /* standard GPL header */

  /**
    @file
    *exhaustive* description of the interface you provide.
    This file is the main user documentation of the new service
  */
  #ifdef __cplusplus
  extern "C" {
  #endif

  extern struct foo_service_st {
    int (*foo_func1_ptr)(...);  /* fix the prototype as appropriate */
    void (*foo_func2_ptr)(...); /* fix the prototype as appropriate */
  } *foo_service;

  #ifdef MYSQL_DYNAMIC_PLUGIN

  #define foo_func1(...) foo_service->foo_func1_ptr(...)
  #define foo_func2(...) foo_service->foo_func2_ptr(...)

  #else

  int foo_func1(...);  /* fix the prototype as appropriate */
  void foo_func2(...); /* fix the prototype as appropriate */

  #endif

  #ifdef __cplusplus
  }
  #endif

  #define MYSQL_SERVICE_FOO_INCLUDED
  #endif
==================================================================

the service_foo.h file should be self-contained, if it needs system headers -
include them in it, e.g. if you use size_t - #include <stdlib.h>

it should also declare all the accompanying data structures, as necessary
(e.g. thd_alloc_service declares MYSQL_LEX_STRING).

3. add the new file to include/mysql/services.h
4. increase the minor plugin ABI version in include/mysql/plugin.h
   (MARIA_PLUGIN_INTERFACE_VERSION = MARIA_PLUGIN_INTERFACE_VERSION+1)
   don't forget to update test result! e.g. use something like
   grep '\s\<1\.11\>' -r mysql-test
5. add the version of your service to include/service_versions.h:
==================================================================
    #define VERSION_foo 0x0100
==================================================================

6. create a new file libservices/foo_service.h using the following template:
==================================================================
  /* GPL header */
  #include <service_versions.h>
  SERVICE_VERSION foo_service= (void*)VERSION_foo;
==================================================================

7. add the new file to libservices/CMakeLists.txt (MYSQLSERVICES_SOURCES)
8. Add all new files to repository (bzr add)
9. and finally, register your service for dynamic linking in
    sql/sql_plugin_services.ic as follows:
9.1 fill in the service structure:
==================================================================
  static struct foo_service_st foo_handler = {
    foo_func1,
    foo_func2
  }
==================================================================

9.2 and add it to the list of services

==================================================================
    { "foo_service", VERSION_foo, &foo_handler }
==================================================================

that's all.