MySQL  8.0.17
Source Code Documentation
service.h
Go to the documentation of this file.
1 /* Copyright (c) 2016, 2019, Oracle and/or its affiliates. All rights reserved.
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 */
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