MySQL 8.0.33
Source Code Documentation
service.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 SERVICE_H
24#define SERVICE_H
25
26/**
27 Specific type for the service status return values.
28
29 0 is false, non-zero is true. Corresponds to C++ bool.
30
31 @sa DEFINE_BOOL_METHOD, DECLARE_BOOL_METHOD
32*/
34
35/**
36 @page PAGE_COMPONENTS_SERVICE A Service and a Service Implementation
37
38 The Service is basic concept of the Components subsystem. A Service is a
39 named, well-defined stateless interface to one functionality, expressed as a
40 list of pointers to a specific methods. The service name will consist of ASCII
41 symbols excluding the dot ('.') symbol. Each Service will be accompanied with
42 a (part of a) header file that defines the Service allowing other Components
43 to consume it. Each Service should work only on basic C types and structures
44 of these types to prevent problems with not fully-defined C++ objects ABI. The
45 Service is a default way to operate inside the Components subsystem as a mean
46 to show that one is interested only on functionality interface, not its exact
47 implementation. The Services are not versioned - any change to interface must
48 require Service being copied to one with different name before applying
49 changes. The Services by itself do not carry any state, all methods are
50 stateless. This does not prevent one from having some state-carrying objects
51 created and returned as handles to them. Such concept is shown for example in
52 create(), get() and release() methods of the registry_query Service. This
53 concept relies on implementation of generator of the Opaque pointers with
54 d-pointer described here: https://en.wikipedia.org/wiki/Opaque_pointer .
55
56 For any specific Service a Service Implementation is defined as a structure
57 of the Service type filled with pointers to methods of specified
58 implementation. The name of the Service Implementation is a name of the
59 Service and the implementation related name separated with a dot. In most
60 cases the implementation related name should be the Component name in which it
61 is being defined. Each Service can have several Service Implementations.
62
63 @file include/mysql/components/service.h
64*/
65
66/**
67 Generates the standard Service type name. It does not have const specifier,
68 it should be used only when really necessary.
69*/
70#define SERVICE_TYPE_NO_CONST(name) mysql_service_##name##_t
71
72/**
73 Generates the standard Service type name.
74*/
75#define SERVICE_TYPE(name) const SERVICE_TYPE_NO_CONST(name)
76
77/**
78 Declares a new Service. It creates a structure for pointers to Service
79 methods. A list of methods defined using DECLARE_METHOD and
80 DECLARE_BOOL_METHOD macros must follow this macro, with a closing
81 END_SERVICE_DEFINITION macro usage.
82
83 @param name Service name, must be a valid C name.
84*/
85#define BEGIN_SERVICE_DEFINITION(name) typedef struct s_mysql_##name {
86/**
87 A macro to end the last Service definition started with the
88 BEGIN_SERVICE_DEFINITION macro.
89*/
90#define END_SERVICE_DEFINITION(name) \
91 } \
92 SERVICE_TYPE_NO_CONST(name);
93/**
94 Declares a method as a part of the Service definition. To be used within the
95 SERVICE_DEFINITION macro.
96
97 @param retval Type of the return value for the method declaration. Should be a
98 simple type or structure, not a C++ object with undefined ABI.
99 @param name Name of the method, must be a valid C name.
100 @param args The list of arguments of the method taken in parentheses.
101*/
102#define DECLARE_METHOD(retval, name, args) retval(*name) args
103
104/**
105 Declares a method that returns bool as a part of the Service definition. To be
106 used within the SERVICE_DEFINITION macro.
107
108 @param name Name of the method, must be a valid C name.
109 @param args The list of arguments of the method taken in parentheses.
110*/
111#define DECLARE_BOOL_METHOD(name, args) \
112 DECLARE_METHOD(mysql_service_status_t, name, args)
113
114/**
115 Defines an object type that is meant for carrying handles to the
116 implementation-specific objects used in the Service interface, but without
117 their structure exposed, keeping it as an abstraction. This follows a Opaque
118 Pointer design pattern, see more: https://en.wikipedia.org/wiki/Opaque_pointer
119 If you would like to have a C++ RAII class to manage the resource with
120 additional methods to call raw service calls, please create your class
121 {handle_name} instead of following macro. Please make sure it does not use any
122 virtual methods to keep binary compatibility, and try use only one member, the
123 d-pointer to hide all implementation details and keep headers unmodified from
124 the point of publishing it.
125
126 @param name Handle name, must be a valid C name.
127*/
128#define DEFINE_SERVICE_HANDLE(name) typedef struct name##_imp *name
129
130#endif /* SERVICE_H */
int mysql_service_status_t
Specific type for the service status return values.
Definition: service.h:33