summaryrefslogtreecommitdiffstats
path: root/libservices/HOWTO
diff options
context:
space:
mode:
Diffstat (limited to 'libservices/HOWTO')
-rw-r--r--libservices/HOWTO103
1 files changed, 103 insertions, 0 deletions
diff --git a/libservices/HOWTO b/libservices/HOWTO
new file mode 100644
index 00000000..6a581bf2
--- /dev/null
+++ b/libservices/HOWTO
@@ -0,0 +1,103 @@
+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.c 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 (git 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.
+