MySQL 8.0.31
Source Code Documentation
registry.h
Go to the documentation of this file.
1/* Copyright (c) 2016, 2022, 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 MYSQL_REGISTRY_H
24#define MYSQL_REGISTRY_H
25
27#include <stdint.h>
28
29/**
30 A handle type for acquired Service.
31*/
33
34/**
35 A handle type for a iterator to a Service Implementation.
36*/
38/**
39 A handle type for a iterator to metadata of some Service Implementation.
40*/
42
43/**
44 Service for acquiring and releasing references to all registered Service
45 Implementations.
46*/
48/**
49 Finds and acquires a Service by name. A name of the Service or the Service
50 Implementation can be specified. In case of the Service name, the default
51 Service Implementation for Service specified will be returned.
52
53 @param service_name Name of Service or Service Implementation to acquire.
54 @param [out] out_service Pointer to Service handle to set acquired Service.
55 @return Status of performed operation
56 @retval false success
57 @retval true failure
58*/
60 (const char *service_name, my_h_service *out_service));
61/**
62 Finds a Service by name. If there is a Service Implementation with the same
63 Component part of name as the input Service then the found Service is
64 returned.
65
66 @param service_name Name of Service or Service Implementation to acquire.
67 @param service Service handle already acquired Service Implementation.
68 @param [out] out_service Pointer to Service Implementation handle to set
69 acquired Service Implementation.
70 @return Status of performed operation
71 @retval false success
72 @retval true failure
73*/
74DECLARE_BOOL_METHOD(acquire_related,
75 (const char *service_name, my_h_service service,
76 my_h_service *out_service));
77/**
78 Releases the Service Implementation previously acquired. After the call to
79 this method the usage of the Service Implementation handle will lead to
80 unpredicted results.
81
82 @param service Service Implementation handle of already acquired Service.
83 @return Status of performed operation
84 @retval false success
85 @retval true failure
86*/
89
90/**
91 Service for managing list of registered Service Implementations.
92*/
93BEGIN_SERVICE_DEFINITION(registry_registration)
94/**
95 Registers a new Service Implementation. If it is the first Service
96 Implementation for the specified Service then it is made a default one.
97
98 @param service_implementation_name Name of the Service Implementation to
99 register.
100 @param ptr Pointer to the Service Implementation structure.
101 @return Status of performed operation
102 @retval false success
103 @retval true failure
104*/
105DECLARE_BOOL_METHOD(register_service, (const char *service_implementation_name,
107/**
108 Removes previously registered Service Implementation from registry. If it is
109 the default one for specified Service then any one still registered is made
110 default. If there is no other, the default entry is removed from the
111 Registry too.
112
113 @param service_implementation_name Name of the Service Implementation to
114 unregister.
115 @return Status of performed operation
116 @retval false success
117 @retval true Failure. May happen when Service is still being referenced.
118*/
119DECLARE_BOOL_METHOD(unregister, (const char *service_implementation_name));
120/**
121 Sets new default Service Implementation for corresponding Service name.
122
123 @param service_implementation_name Name of the Service Implementation to
124 set as default one.
125 @return Status of performed operation
126 @retval false success
127 @retval true failure
128*/
129DECLARE_BOOL_METHOD(set_default, (const char *service_implementation_name));
130END_SERVICE_DEFINITION(registry_registration)
131
132/**
133 Service for listing all Service Implementations by iterator.
134*/
136/**
137 Creates iterator that iterates through all registered Service
138 Implementations. If successful it leaves read lock on the Registry until
139 iterator is released. The starting point of iteration may be specified
140 to be on one particular Service Implementation. The iterator will move
141 through all Service Implementations and additionally through all default
142 Service Implementation additionally, i.e. the default Service Implementation
143 will be returned twice. If no name is specified for search, iterator will be
144 positioned on the first Service Implementation.
145
146 @warning Takes and keeps a lock on the registry until the iterator is closed!
147
148 @param service_name_pattern Name of Service or Service Implementation to
149 start iteration from. May be empty string or NULL pointer, in which case
150 iteration starts from the first Service Implementation.
151 @param [out] out_iterator Pointer to the Service Implementation iterator
152 handle.
153 @return Status of performed operation
154 @retval false success
155 @retval true failure
156*/
157DECLARE_BOOL_METHOD(create, (const char *service_name_pattern,
158 my_h_service_iterator *out_iterator));
159/**
160 Gets name of Service pointed to by iterator. The pointer returned will last
161 at least up to the moment of call to the release() method on the iterator.
162
163 @param iterator Service Implementation iterator handle.
164 @param [out] out_name Pointer to string with name to set result pointer to.
165 @return Status of performed operation
166 @retval false success
167 @retval true Failure, may be caused when called on iterator that went
168 through all values already.
169*/
170DECLARE_BOOL_METHOD(get, (my_h_service_iterator iter, const char **out_name));
171/**
172 Advances specified iterator to next element. Will succeed but return true if
173 it reaches one-past-last element.
174
175 @note You should collect the service names in a local cache, close the
176 iterator and only then try to resolve the names using the other registry
177 services.
178
179 @warning Make sure to close the iterator before looking up the name into
180 the registry! Otherwise undefined behavior will ensure. Most probably a
181 deadlock.
182
183 @param iterator Service Implementation iterator handle.
184 @return Status of performed operation and validity of iterator after
185 operation.
186 @retval false success
187 @retval true Failure or called on iterator that was on last element.
188*/
190/**
191 Checks if specified iterator is valid, i.e. have not reached one-past-last
192 element.
193
194 @param iterator Service Implementation iterator handle.
195 @return Validity of iterator
196 @retval false Valid
197 @retval true Invalid or reached one-past-last element.
198*/
200/**
201 Releases the Service Implementations iterator. Releases read lock on the
202 Registry.
203
204 @param iterator Service Implementation iterator handle.
205 @return Status of performed operation
206 @retval false success
207 @retval true failure
208*/
211
212/**
213 Service for listing all metadata for a Service Implementation specified by
214 the given iterator.
215*/
216BEGIN_SERVICE_DEFINITION(registry_metadata_enumerate)
217/**
218 Creates a iterator that iterates through all metadata for the object pointed
219 by the specified iterator. If successful it leaves read lock on the registry
220 until the iterator is released.
221
222 @param iterator A iterator that points to object to get the metadata
223 iterator for.
224 @param [out] out_iterator Pointer to metadata iterator handle.
225 @return Status of performed operation
226 @retval false success
227 @retval true failure
228*/
231/**
232 Gets the key and value of the metadata pointed to by the specified iterator.
233 The pointers returned will last at least up to the moment of call to the
234 release() method on the iterator.
235
236 @param iterator Metadata iterator handle.
237 @param [out] out_name A pointer to the string with the key to set the result
238 pointer to.
239 @param [out] out_value A pointer to the string with the metadata value to
240 set the result pointer to.
241 @return Status of performed operation
242 @retval false success
243 @retval true Failure, may be caused when called on the iterator that went
244 through all values already.
245*/
247 const char **name, const char **value));
248/**
249 Advances specified iterator to next element. Will fail if it reaches
250 one-past-last element.
251
252 @param iterator Metadata iterator handle.
253 @return Status of performed operation
254 @retval false success
255 @retval true Failure, may be caused when called on iterator that was on last
256 element.
257*/
259/**
260 Checks if specified iterator is valid, i.e. have not reached one-past-last
261 element.
262
263 @param iterator Metadata iterator handle.
264 @return Validity of iterator
265 @retval false Valid
266 @retval true Invalid or reached one-past-last element.
267*/
269/**
270 Releases the specified iterator. Releases read lock on the registry.
271
272 @param iterator Metadata iterator handle.
273 @return Status of performed operation
274 @retval false success
275 @retval true failure
276*/
278END_SERVICE_DEFINITION(registry_metadata_enumerate)
279
280/**
281 Service to query specified metadata key directly for the specified Service
282 Implementation by iterator to it.
283*/
284BEGIN_SERVICE_DEFINITION(registry_metadata_query)
285/**
286 Gets the key and value of the metadata pointed to by the specified object
287 iterator. The pointer returned will last at least up to the moment of call
288 to the release() method on the iterator.
289
290 @param iterator A iterator that points to object to get the metadata
291 iterator for.
292 @param name A pointer to the string with the key to set the result
293 pointer to.
294 @param [out] out_value A pointer to the string with the metadata value to
295 set the result pointer to.
296 @return Status of performed operation
297 @retval false success
298 @retval true Failure, may be caused when called on the iterator that went
299 through all values already.
300*/
301DECLARE_BOOL_METHOD(get_value, (my_h_service_iterator iterator,
302 const char *name, const char **value));
303END_SERVICE_DEFINITION(registry_metadata_query)
304
305#endif /* MYSQL_REGISTRY_H */
struct my_h_service_imp * my_h_service
A handle type for acquired Service.
Definition: registry.h:32
bool is_valid(const dd::Spatial_reference_system *srs, const Geometry *g, const char *func_name, bool *is_valid) noexcept
Decides if a geometry is valid.
Definition: is_valid.cc:94
static mysql_service_status_t get(reference_caching_cache cache, unsigned service_name_index, const my_h_service **refs) noexcept
Definition: component.cc:113
static mysql_service_status_t create(const char *service_names[], reference_caching_channel *out_channel) noexcept
Definition: component.cc:35
#define DECLARE_METHOD(retval, name, args)
Declares a method as a part of the Service definition.
Definition: service.h:102
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
#define DEFINE_SERVICE_HANDLE(name)
Defines an object type that is meant for carrying handles to the implementation-specific objects used...
Definition: service.h:128
#define DECLARE_BOOL_METHOD(name, args)
Declares a method that returns bool as a part of the Service definition.
Definition: service.h:111
case opt name
Definition: sslopt-case.h:32
Definition: registry.cc:57
Definition: registry.cc:62