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
3
This program is free software; you can redistribute it and/or modify
4
it under the terms of the GNU General Public License, version 2.0,
5
as published by the Free Software Foundation.
6
7
This program is also distributed with certain software (including
8
but not limited to OpenSSL) that is licensed under separate terms,
9
as designated in a particular file or component or in included license
10
documentation. The authors of MySQL hereby grant you an additional
11
permission to link the program and your derivative works with the
12
separately licensed software that they have included with MySQL.
13
14
This program is distributed in the hope that it will be useful,
15
but WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17
GNU General Public License, version 2.0, for more details.
18
19
You should have received a copy of the GNU General Public License
20
along with this program; if not, write to the Free Software
21
Foundation, 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
*/
33
typedef
int
mysql_service_status_t
;
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 */
mysql_service_status_t
int mysql_service_status_t
Specific type for the service status return values.
Definition:
service.h:33
include
mysql
components
service.h
Generated by
1.9.2