MySQL 8.2.0
Source Code Documentation
component_implementation.h
Go to the documentation of this file.
1/* Copyright (c) 2016, 2023, Oracle and/or its affiliates.
2
3This program is free software; you can redistribute it and/or modify
4it under the terms of the GNU General Public License, version 2.0,
5as published by the Free Software Foundation.
6
7This program is also distributed with certain software (including
8but not limited to OpenSSL) that is licensed under separate terms,
9as designated in a particular file or component or in included license
10documentation. The authors of MySQL hereby grant you an additional
11permission to link the program and your derivative works with the
12separately licensed software that they have included with MySQL.
13
14This program is distributed in the hope that it will be useful,
15but WITHOUT ANY WARRANTY; without even the implied warranty of
16MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17GNU General Public License, version 2.0, for more details.
18
19You should have received a copy of the GNU General Public License
20along with this program; if not, write to the Free Software
21Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef COMPONENT_IMPLEMENTATION_H
24#define COMPONENT_IMPLEMENTATION_H
25
28#include <cstddef> // NULL
30
31/**
32 @page PAGE_COMPONENTS_COMPONENT A Component
33
34 A component is a code container that contains one or more Service
35 Implementations. Components can be internal (part of the MySQL Server binary)
36 and external (hosted in a OS binary file different from the one of the MySQL
37 Server).
38
39 Each component will have:
40 - Name
41 - List of service implementations it provides.
42 - List of services or service implementations it needs.
43 - Initialization function that's called when a container is loaded. Takes a
44 reference to the currently active service registry implementation.
45 - De-initialization function that's called when a container unload is
46 requested.
47
48 Opposite to old plugin infrastructure, Components don't need linkage against
49 mysqld executable, neither on Linux nor Windows. In fact, in Components we
50 strongly discourage from linking against mysqld executable at all, as it
51 presents significant threat to them being independent and using only
52 Components infrastructure to communicate with other parts of software.
53
54 @subpage PAGE_COMPONENTS_IMPLEMENTATION
55
56 @page PAGE_COMPONENTS_IMPLEMENTATION MySQL Component - creating implementation
57 The Component for the Dynamic Loader needs to be a dynamic library (for
58 example .so or .dll) with specified entry-point method. The only exception is
59 the MySQL server, for which, for now, it will be statically linked. All these
60 implementation details are hidden away by macros defined in header files.
61 All macros to define Services are specified in service.h, for defining Service
62 Implementations in service_implementation.h and for specifying Components in
63 component_implementation.h.
64
65 @section EXAMPLE The Component example
66 Example Components are located in components/example directory. These
67 Components are used also for unit and MTR test, which assures these Components
68 are fully functional and they quality is maintained. The example Services are
69 defined in example_services.h, while implemented in three example Components
70 defined in files example_component1.cc, example_component2.cc,
71 and example_component3.cc. These files are specifically prepared to be used as
72 examples as they provide simplicity and an extensive documentation. The
73 following tutorial bases on these Components and will try to show a process to
74 create similar.
75
76 @subsection EXAMPLE_SERVICES Services defined in the example
77 Example contains definition of 3 Services which will be used to show a general
78 idea of services, basic implementations and simple example of one of concepts
79 possible with the Component Infrastructure. These example Services are defined
80 in example_services.h and are s_mysql_greetings,
81 s_mysql_greetings_localization and s_mysql_example_math.
82
83 @section TROUBLESHOOTING Common problems
84
85 @section TUTORIAL Step by step tutorial for creating new Component
86 The creation of component is a mean to get some functionality exported for the
87 Components infrastructure. It can be divided into several steps:
88 -# %List all high level functionalities Component is planned to have
89 implemented. This will assure we know exactly what we need to benefit from
90 next steps. In the example, we would like to have a "Hello, World!" string
91 provider and simple math functions.
92 -# Look for existing Services, that are designed specifically to provide some
93 part of the new functionalities to reuse them, or other that are in any
94 degree similar in functionality, design or use cases to use as an example.
95 The Component infrastructure is highly oriented on reuse of Services and
96 will benefit with every reuse case, as it will decrease total size of
97 Services. In the example the existing base of Services is really small,
98 with the core Components infrastructure Services available only leading to
99 no reuse possible.
100 -# Design list of functions needed to provide all functionalities. Try to make
101 they follow existing patterns and ideas, possibly having some identical to
102 existing ones.
103 -# Try to separate groups of functions that specify some complete part of
104 functionality into separate small Services to improve re-usability. Also,
105 try to separate groups that seem to have more potential to be extended or
106 modified in future, because changing existing Services is forbidden, in
107 such a case this will lead to a lot of functions in Services that will be
108 duplicates and will introduce more boilerplate code to implement them.
109 Remove all functions that can be found in fully reused existing Services.
110 -# Create definitions of Services, ideally one Service per file, or a group of
111 really closely connected Services. In most cases you want to make these
112 definitions public, in case of MySQL that means placing them in
113 include/mysql/components/services/ directory to include them in mysql-dev
114 package. See example_services.h, which in contrary is not made public and
115 resides in example component source directory.
116 -# Create declarations of all handles, the Opaque pointers for all opaque
117 objects that are meant to be returned to the Services users. See usages of
118 DEFINE_SERVICE_HANDLE in registry.h.
119 -# Create basic structure of new Component. Use BEGIN_COMPONENT_PROVIDES,
120 BEGIN_COMPONENT_REQUIRES, BEGIN_COMPONENT_METADATA, DECLARE_COMPONENT and
121 DECLARE_LIBRARY_COMPONENTS. Fill in all information necessary to describe
122 the new Component extensively. The example_component1.cc and
123 example_component2.cc shows how structure should look like, and in
124 example_component3.cc there is an example with additional Service
125 references, for which placeholder definitions are kept in header file of the
126 new Component, see example_component3.h. Note the placeholder for the
127 Registry Service, which is available by default in every component.
128 -# Create implementations of the desired Service interfaces. Implement handles
129 used, as for example my_h_service_iterator_imp and
130 my_h_service_metadata_iterator_imp in registry.cc. Create separate
131 source and header files for each Service or closely connected group of
132 Services. Remember to include the header file for Service Implementation in
133 the Service Implementation source file to have no linkage problems.
134 The Service Implementations in english_greeting_service_imp.cc and
135 simple_example_math_imp.cc are implementations used in example_component1,
136 polish_greeting_service_imp.cc and example_math_wrapping_imp.cc are
137 implementations for example_component2 and example_component3 respectively.
138 -# Make sure component is loaded/initialized before using its services.
139 Atomic variable is_intialized represents the state of the component.
140 Please check the details about the variable from validate_password_imp.cc
141 file.
142 -# Using registry acquire/release services inside component's init/deint
143 functions is not supported. All the required services for the component
144 has to be specified under BEGIN_COMPONENT_REQUIRES section only.
145 .
146
147 @file include/mysql/components/component_implementation.h
148 Specifies macros to define Components.
149*/
150
151/**
152 Declares a component. For specified name following macros must be executed
153 earlier: BEGIN_COMPONENT_PROVIDES, BEGIN_COMPONENT_REQUIRES and
154 BEGIN_COMPONENT_METADATA.
155 It fills mysql_component_t structure with all of the component data. The
156 info object will be named mysql_component_{source_name}.
157 After this macro it is required to specify comma-separated pointers to
158 initialize and deinitialize methods for components to be used during loading
159 and unloading of component.
160
161 @param source_name The source name used in other macros.
162 @param name Name string with human readable name.
163*/
164#define DECLARE_COMPONENT(source_name, name) \
165 mysql_component_t mysql_component_##source_name = { \
166 name, __##source_name##_provides, __##source_name##_requires, \
167 __##source_name##_metadata,
168
169/**
170 A macro to end the last declaration of a Component.
171*/
172#define END_DECLARE_COMPONENT() }
173
174/**
175 Creates a service implementation list that are provided by specified
176 component. Only a series of PROVIDES_SERVICE and PROVIDES_CUSTOM_SERVICE
177 macros are expected to be used after this macro and before the
178 END_COMPONENT_PROVIDES counterpart.
179
180 @param name Component name.
181*/
182#define BEGIN_COMPONENT_PROVIDES(name) \
183 static struct mysql_service_ref_t __##name##_provides[] = {
184/**
185 Declare a Service Implementation provided by a Component. It assumes standard
186 Service Implementation name to be referenced.
187 @sa SERVICE_IMPLEMENTATION
188
189 @param component Component name.
190 @param service A Service name for which the Service Implementation will be
191 added.
192*/
193#define PROVIDES_SERVICE(component, service) \
194 { \
195#service "." #component, \
196 const_cast < void *> \
197 ((const void *)&SERVICE_IMPLEMENTATION(component, service)) \
198 }
199
200/**
201 A macro to end the last declaration started with the BEGIN_COMPONENT_PROVIDES.
202*/
203#define END_COMPONENT_PROVIDES() \
204 { NULL, NULL } \
205 }
206
207/**
208 A macro to specify requirements of the component. Creates a structure with
209 a list for requirements and pointers to their placeholders.
210
211 @param name Name of component.
212*/
213#define BEGIN_COMPONENT_REQUIRES_WITHOUT_REGISTRY(name) \
214 static struct mysql_service_placeholder_ref_t __##name##_requires[] = {
215/**
216 A macro to specify requirements of the component. Creates a placeholder for
217 the Registry service and structure with a list for requirements and
218 pointers to their placeholders, adding the Registry service as first element.
219
220 @param name Name of component.
221*/
222#define BEGIN_COMPONENT_REQUIRES(name) \
223 REQUIRES_SERVICE_PLACEHOLDER(registry); \
224 static struct mysql_service_placeholder_ref_t __##name##_requires[] = { \
225 REQUIRES_SERVICE(registry),
226
227/**
228 Create a service placeholder, based on the service name.
229
230 A service placeholder is a pointer to the service.
231 It is named mysql_service_{service name}.
232
233 This pointer is initialized by the framework upon loading a component,
234 based on the component dependencies declared by @ref REQUIRES_SERVICE.
235
236 When defining a service 'foo', in the header file for the service,
237 a service placeholder is declared as follows:
238
239 @verbatim
240 extern REQUIRES_SERVICE_PLACEHOLDER(foo);
241 @endverbatim
242
243 When implementing a component 'bar', which requires the service 'foo',
244 the definition of the component 'bar' should contain the following:
245
246 @verbatim
247 REQUIRES_SERVICE_PLACEHOLDER(foo);
248
249 BEGIN_COMPONENT_REQUIRES(bar)
250 REQUIRES_SERVICE(foo),
251 ...
252 END_COMPONENT_REQUIRES();
253 @endverbatim
254
255 The code in the implementation of service 'bar' can use
256 the service placeholder pointer to invoke apis in service foo:
257
258 @verbatim
259 mysql_service_foo->some_api();
260 @endverbatim
261
262 Similarly to use a service in another service within the same
263 component. Call the implementation of the service directly in
264 the other service since both services belong to the same component.
265 Suppose mysql_bar_imp and mysql_foo_imp services belongs to the
266 same component. And if foo service is required in bar service then
267 use below method.
268
269 @verbatim
270 mysql_bar_imp::bar_api() {
271 ...
272 mysql_foo_imp::foo_api();
273 ...
274 }
275 @endverbatim
276
277 @param service A referenced Service name.
278*/
279#define REQUIRES_SERVICE_PLACEHOLDER(service) \
280 SERVICE_TYPE(service) * mysql_service_##service
281
282/**
283 Create a service placeholder, with an arbitrary name.
284
285 Identical to @ref REQUIRES_SERVICE_PLACEHOLDER(),
286 except that the service handle name is provided
287 by the caller, instead of being derived from the service type.
288
289 Use with @ref REQUIRES_SERVICE_AS().
290
291 @param service A referenced Service name.
292 @param name Service handle name.
293*/
294
295#define REQUIRES_SERVICE_PLACEHOLDER_AS(service, name) \
296 SERVICE_TYPE(service) * name
297
298/**
299 Adds a Service requirement with a pointer to placeholder to the list of
300 components.
301
302 @param service A referenced Service name.
303*/
304#define REQUIRES_SERVICE(service) \
305 { \
306#service, \
307 static_cast < void **> \
308 (static_cast <void *>(const_cast <mysql_service_##service##_t **>( \
309 &mysql_service_##service))) \
310 }
311
312/**
313 Adds a Service requirement with a pointer to placeholder to the list of
314 components.
315
316 Use with @ref REQUIRES_SERVICE_PLACEHOLDER_AS().
317
318 @param service A referenced Service name.
319 @param name Service handle name.
320*/
321#define REQUIRES_SERVICE_AS(service, name) \
322 { \
323#service, \
324 static_cast < void **>(static_cast <void *>( \
325 const_cast <mysql_service_##service##_t **>(&name))) \
326 }
327
328/**
329 Use this macro to reference the service placeholder as defined by the
330 REQUIRES_SERVICE_PLACEHOLDER macro.
331
332Example:
333 REQUIRES_SERVICE_PLACEHOLDER(foo);
334
335 ...
336
337 code() {
338 ....
339 SERVICE_PLACEHOLDER(foo)->bar(1);
340 ...
341 }
342
343 BEGIN_COMPONENT_REQUIRES(comp)
344 REQUIRES_SERVICE(foo);
345 END_COMPONENT_REQUIRES(comp)
346
347 @param service A valid service name.
348*/
349#define SERVICE_PLACEHOLDER(service) mysql_service_##service
350
351/**
352 A macro to end the last declaration started with the BEGIN_COMPONENT_REQUIRES.
353*/
354#define END_COMPONENT_REQUIRES() \
355 { NULL, NULL } \
356 }
357
358/**
359 A macro to specify metadata of the component. Creates a list of metadata.
360 Only a series of METADATA macros are expected to be used after this macro and
361 before the END_COMPONENT_METADATA counterpart.
362
363 @param name Name of component.
364*/
365#define BEGIN_COMPONENT_METADATA(name) \
366 static struct mysql_metadata_ref_t __##name##_metadata[] = {
367/**
368 Adds a Service requirement with a pointer to placeholder to the list of
369 components.
370
371 @param key A string name of the metadata to add.
372 @param value A string value of the metadata to add.
373*/
374#define METADATA(key, value) \
375 { key, value }
376
377/**
378 A macro to end the last declaration started with the BEGIN_COMPONENT_METADATA.
379*/
380#define END_COMPONENT_METADATA() \
381 { NULL, NULL } \
382 }
383
384/* On Windows, exports from DLL need to be declared.
385 Also, plug-in needs to be declared as extern "C" because MSVC
386 unlike other compilers, uses C++ mangling for variables not only
387 for functions. */
388#if defined(_MSC_VER) /* Microsoft */
389#ifdef __cplusplus
390#define DLL_EXPORT extern "C" __declspec(dllexport)
391#define DLL_IMPORT extern "C" __declspec(dllimport)
392#else
393#define DLL_EXPORT __declspec(dllexport)
394#define DLL_IMPORT __declspec(dllimport)
395#endif
396#else /* non _MSC_VER */
397#ifdef __cplusplus
398#define DLL_EXPORT extern "C" __attribute__((visibility("default")))
399#define DLL_IMPORT
400#else
401#define DLL_EXPORT __attribute__((visibility("default")))
402#define DLL_IMPORT
403#endif
404#endif
405
406/**
407 Creates a list of component implementations included in this dynamic library.
408 It can be used only once in whole library. It defines an entry point method
409 for library to be used with the Dynamic Loader. A list of pointers to
410 Component structures is required after this macro up to the usage of
411 the END_DECLARE_LIBRARY_COMPONENTS macro. Current implementation of the
412 Dynamic Loader supports only one Component being specified in the library.
413*/
414#define DECLARE_LIBRARY_COMPONENTS \
415 mysql_component_t *library_components_list = {
416/**
417 A macro to end the last declaration started with the
418 DECLARE_LIBRARY_COMPONENTS.
419*/
420#define END_DECLARE_LIBRARY_COMPONENTS \
421 } \
422 ; \
423 DLL_EXPORT mysql_component_t *list_components() { \
424 return library_components_list; \
425 }
426
427/**
428 Defines a reference to the specified Component data info structure.
429*/
430#define COMPONENT_REF(name) mysql_component_##name
431
432/**
433 This is the component module entry function, used to get the component's
434 structure to register the required services.
435*/
436#define COMPONENT_ENTRY_FUNC "list_components"
437
438#endif /* COMPONENT_IMPLEMENTATION_H */
Specifies macros to define Service Implementations.