BDE 4.14.0 Production release
Loading...
Searching...
No Matches
bdlm_metricsregistry.h
Go to the documentation of this file.
1/// @file bdlm_metricsregistry.h
2///
3/// The content of this file has been pre-processed for Doxygen.
4///
5
6
7// bdlm_metricsregistry.h -*-C++-*-
8
9#ifndef INCLUDED_BDLM_METRICSREGISTRY
10#define INCLUDED_BDLM_METRICSREGISTRY
11
12#include <bsls_ident.h>
13BSLS_IDENT("$Id: $")
14
15/// @defgroup bdlm_metricsregistry bdlm_metricsregistry
16/// @brief Provide a transferable registry of metric registrations.
17/// @addtogroup bdl
18/// @{
19/// @addtogroup bdlm
20/// @{
21/// @addtogroup bdlm_metricsregistry
22/// @{
23///
24/// <h1> Outline </h1>
25/// * <a href="#bdlm_metricsregistry-purpose"> Purpose</a>
26/// * <a href="#bdlm_metricsregistry-classes"> Classes </a>
27/// * <a href="#bdlm_metricsregistry-description"> Description </a>
28/// * <a href="#bdlm_metricsregistry-thread-safety"> Thread Safety </a>
29/// * <a href="#bdlm_metricsregistry-usage"> Usage </a>
30/// * <a href="#bdlm_metricsregistry-example-1-using-bdlm-metricsregistry"> Example 1: Using bdlm::MetricsRegistry </a>
31///
32/// # Purpose {#bdlm_metricsregistry-purpose}
33/// Provide a transferable registry of metric registrations.
34///
35/// @deprecated This component is not ready for public use.
36///
37/// # Classes {#bdlm_metricsregistry-classes}
38///
39/// - bdlm::MetricsRegistry: transferable registry of metric registrations
40/// - bdlm::MetricsRegistryRegistrationHandle: registration handle providing RAII
41///
42/// # Description {#bdlm_metricsregistry-description}
43/// This component contains a mechanism, `bdlm::MetricsRegistry`,
44/// that provides a registry of metrics that is transferable to implementations
45/// of the `bdlm::MetricsAdapter` protocol. `bdlm`, as a low-level metrics
46/// facility, does not directly manage schedulers to collect metrics values or
47/// publishers to publish those value. Instead `bdlm` is designed to allow
48/// applications to plug in different high-level feature-rich metrics collection
49/// and publication frameworks (without requiring a library dependency on those
50/// frameworks). A `bdlm::MetricsRegistry` effectively serves as a proxy for a
51/// higher-level metrics collection system implementing the `MetricsAdapter`
52/// protocol -- it keeps track of registered metrics allowing a higher-level
53/// metrics subsystem to be installed (by calling 'setMetricsAdapter) at any
54/// time, either before or after a metric is registered.
55///
56/// A singleton instance of `MetricsRegistry` is available from the
57/// `defaultInstance` class method. This component also provides a registration
58/// handle class, `bdlm::MetricsRegistryRegistrationHandle`, that provides RAII
59/// semantics for metric registration.
60///
61/// ## Thread Safety {#bdlm_metricsregistry-thread-safety}
62///
63///
64/// The class `bdlm::MetricsRegistry` is *thread-aware* (see
65/// {@ref bsldoc_glossary |Thread-Aware}), and
66/// `bdlm::MetricsRegistryRegistrationHandle` is *minimally thread-safe* (see
67/// {@ref bsldoc_glossary |Minimally Thread-Safe}).
68///
69/// ## Usage {#bdlm_metricsregistry-usage}
70///
71///
72/// This section illustrates intended use of this component.
73///
74/// ### Example 1: Using bdlm::MetricsRegistry {#bdlm_metricsregistry-example-1-using-bdlm-metricsregistry}
75///
76///
77/// This example demonstrates the initialization and usage of the
78/// `bdlm::MetricsRegistry` object, allowing for registering metric callback
79/// functions with the `bdlm` monitoring system.
80///
81/// First, we declare a class that provides some metric for the `bdlm`
82/// monitoring system:
83/// @code
84/// class LowLevelFacility {
85/// // PRIVATE DATA
86/// bdlm::MetricsRegistryRegistrationHandle d_metricHandle;
87/// public:
88/// // CREATORS
89/// explicit LowLevelFacility(bdlm::MetricsRegistry& metricsRegistry =
90/// bdlm::MetricsRegistry::defaultInstance());
91///
92/// // ACCESSORS
93/// int someMetric() const
94/// {
95/// return 0; // just a stub
96/// }
97/// };
98/// @endcode
99/// Next, we provide a metric function to be used during callback registration:
100/// @code
101/// void metricCallback(bdlm::Metric *value, const LowLevelFacility *object)
102/// {
103/// *value = bdlm::Metric::Gauge(object->someMetric());
104/// }
105/// @endcode
106/// Here is the constructor definition that registers the collection callback:
107/// @code
108/// /// Construct a `bdlm::MetricsDescriptor` object to be used when
109/// /// registering the callback function:
110/// LowLevelFacility::LowLevelFacility(bdlm::MetricsRegistry& metricsRegistry)
111/// {
112/// bdlm::MetricDescriptor descriptor("bdlm",
113/// "example",
114/// 1,
115/// "bdlmmetricsregistry",
116/// "bmr",
117/// "identifier");
118///
119/// // Register the collection callback:
120/// metricsRegistry.registerCollectionCallback(
121/// &d_metricHandle,
122/// descriptor,
123/// bdlf::BindUtil::bind(&metricCallback,
124/// bdlf::PlaceHolders::_1,
125/// this));
126/// assert(d_metricHandle.isRegistered());
127/// }
128/// @endcode
129/// Notice that the compiler-supplied destructor is sufficient because the
130/// `d_metricHandle` will deregister the metric on destruction.
131///
132/// Now, we construct a `bdlm::MetricsRegistry` object with a test allocator:
133/// @code
134/// bslma::TestAllocator ta;
135/// bdlm::MetricsRegistry registry(&ta);
136/// assert(registry.numRegisteredCollectionCallbacks() == 0);
137/// @endcode
138/// Then, we create the object and pass the constructed `bdlm::MetricsRegistry`
139/// object there:
140/// @code
141/// {
142/// LowLevelFacility facility(registry);
143/// assert(registry.numRegisteredCollectionCallbacks() == 1);
144/// @endcode
145/// If we don't provide a `bdlm::MetricsRegistry` object explicitly, the default
146/// global instance will be used.
147///
148/// Finally, the callback is removed the monitoring system by the destructor of
149/// `facility` object:
150/// @code
151/// } // 'facility.d_metricHandle.unregister()' is called here
152/// assert(registry.numRegisteredCollectionCallbacks() == 0);
153/// @endcode
154/// @}
155/** @} */
156/** @} */
157
158/** @addtogroup bdl
159 * @{
160 */
161/** @addtogroup bdlm
162 * @{
163 */
164/** @addtogroup bdlm_metricsregistry
165 * @{
166 */
167
168#include <bdlm_metricdescriptor.h>
169#include <bdlm_metricsadapter.h>
170
171#include <bslalg_swaputil.h>
172
173#include <bslma_allocator.h>
175
176#include <bslmf_allocatorargt.h>
177#include <bslmf_movableref.h>
179
180#include <bslstl_sharedptr.h>
181
182#include <bsls_keyword.h>
183
184
185namespace bdlm {
186
187class MetricsRegistryRegistrationHandle;
188class MetricsRegistry_Impl;
189
190 // =====================
191 // class MetricsRegistry
192 // =====================
193
194/// This class implements a mechanism that provides a registry of metrics
195/// that is transferable to implementations of the `bdlm::MetricsAdapter`
196/// protocol. This class is *usually* a singleton.
197///
198/// See @ref bdlm_metricsregistry
200
201 // DATA
203
204 public:
205 // TYPES
208
209 // TRAITS
211
212 // CLASS METHODS
213
214 /// Return a non-`const` reference to the metrics registry singleton.
216
217 // CREATORS
218
219 /// Create a `MetricsRegistry` object that stores the information
220 /// necessary to forward the registration and unregistration of metrics
221 /// to an adapter supplied with `setMetricsRegistry`. Optionally
222 /// specify a `basicAllocator` used to supply memory. If
223 /// `basicAllocator` is 0, the currently installed default allocator is
224 /// used.
225 explicit MetricsRegistry(bslma::Allocator *basicAllocator = 0);
226
227 /// Unregister all registered metrics and destroy this `MetricsRegistry`
228 /// object.
230
231 // MANIPULATORS
232
233 /// Register the metric described by the specified `descriptor` and
234 /// associate it with the specified `callback` to collect data from the
235 /// metric, and load the specified `result` with a handle can be used
236 /// later to unregister the metric. After this operation completes,
237 /// `result->isRegistered()` will be `true`. The metric and associated
238 /// callback remain registered with this registry until either the
239 /// handle is unregistered or destroyed. When a `MetricsAdapter` is
240 /// associated with this registry using `setMetricsAdapter`, this
241 /// objects registers all the registered metrics and callbacks with that
242 /// adapter, and similarly unregisters them if the `MetricAdapter` is
243 /// later disassociated with this registry (either on this objects
244 /// destruction, or due to a call to `removeMetricsAdapter` or
245 /// `setMetricsAdapter`). In this way, a `MetricsRegistry` serves as an
246 /// intermediary between users of `bdlm` that register metrics and the
247 /// subsystem for collecting and publishing metrics being adapted by a
248 /// concrete instance of `bdlm::MetricAdapter`.
251 const bdlm::MetricDescriptor& descriptor,
252 const Callback& callback);
253
254 /// If the specified `adapter` is the currently associated registrar,
255 /// remove all registered metrics from it and disassociate the registry.
256 /// Note that this operation takes an `adapter` to disambiguate
257 /// multiple, potentially concurrent, calls to this method and
258 /// `setMetricsAdapter`.
260
261 /// Configure this metrics registry to register all metrics collection
262 /// callbacks with the specified `adapter`. This operation first, if
263 /// there is already an associated metrics adapter, unregisters all the
264 /// collection callbacks from that adapter, then registers the
265 /// collection callbacks with the new `adapter`.
267
268 // ACCESSORS
269
270 /// Return the number of registered metrics collection callbacks.
272
273 // Aspects
274
275 /// Return the allocator used by this object to supply memory.
277};
278
279 // =======================================
280 // class MetricsRegistryRegistrationHandle
281 // =======================================
282
283/// This class implements a registration handle that provides RAII semantics
284/// for metric registration.
285///
286/// See @ref bdlm_metricsregistry
288
289 // PRIVATE TYPES
291
292 // DATA
293 bsl::weak_ptr<MetricsRegistry_Impl> d_registry; // associated registry
294 MetricsRegistry::CallbackHandle d_handle; // handle for registration
295
296 // PRIVATE CREATORS
297
298 /// Create a `MetricsRegistryRegistrationHandle` object having the
299 /// associated specified `registry` and the specified `handle` in the
300 /// `registry`.
304
305 // FRIENDS
306 friend class MetricsRegistry;
307
308 // NOT IMPLEMENTED
313 public:
314 // CREATORS
315
316 /// Create a `MetricsRegistryRegstrationHandle` object that is not
317 /// associated with a registered metrics collection callback
318 /// (`isRegistered` will return `false`).
320
321 /// Create a `MetricsRegistryRegistrationHandle` object that will manage
322 /// the metric collection callback registration associated with the
323 /// specified `original` handle. After creating this object, `original`
324 /// will no longer manage the registration, and
325 /// `original.isRegistered()` will be `false`. If `original` does not
326 /// manage a registration when this object is created, then neither this
327 /// object nor `original` will manage a registration.
331
332 /// Unregister the metric collection callback associated with this
333 /// handle (if `isRegistered` is `true`), and destroy this object.
335
336 // MANIPULATORS
337
338 /// Unregister the metric collection callback associated with this
339 /// handle (if `isRegistered` is `true`). Take an ownership on the
340 /// metric collection callback registration associated with the
341 /// specified `original` handle. Afterwards, `original` will no longer
342 /// manage the registration, and `original.isRegistered()` will be
343 /// `false`.
347
348 /// Exchange the associated metric collection callback registration with
349 /// the one controlled by the specified `other` handle.
351
352 /// Unregister the metric from the associated registry. Return 0 on
353 /// success, and a non-zero value if this handle is not currently
354 /// associated with a registered metrics collection callback.
356
357 // ACCESSORS
358
359 /// Return `true` if this handle has an associated registered metrics
360 /// collection callback.
361 bool isRegistered() const;
362};
363
364// ============================================================================
365// INLINE DEFINITIONS
366// ============================================================================
367
368 // ---------------------------------------
369 // class MetricsRegistryRegistrationHandle
370 // ---------------------------------------
371
372// CREATORS
373inline
375: d_registry()
376, d_handle(0)
377{
378}
379
380// MANIPULATORS
381inline
384{
385 bslalg::SwapUtil::swap(&d_registry, &other.d_registry);
386 bslalg::SwapUtil::swap(&d_handle, &other.d_handle);
387}
388
389// ACCESSORS
390inline
392{
393 return !d_registry.expired();
394}
395
396} // close package namespace
397
398
399#endif
400
401// ----------------------------------------------------------------------------
402// Copyright 2024 Bloomberg Finance L.P.
403//
404// Licensed under the Apache License, Version 2.0 (the "License");
405// you may not use this file except in compliance with the License.
406// You may obtain a copy of the License at
407//
408// http://www.apache.org/licenses/LICENSE-2.0
409//
410// Unless required by applicable law or agreed to in writing, software
411// distributed under the License is distributed on an "AS IS" BASIS,
412// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
413// See the License for the specific language governing permissions and
414// limitations under the License.
415// ----------------------------- END-OF-FILE ----------------------------------
416
417/** @} */
418/** @} */
419/** @} */
Definition bdlm_metricdescriptor.h:142
Definition bdlm_metricsadapter.h:293
int CallbackHandle
Definition bdlm_metricsadapter.h:297
Definition bdlm_metricsregistry.h:287
void swap(MetricsRegistryRegistrationHandle &other) BSLS_KEYWORD_NOEXCEPT
Definition bdlm_metricsregistry.h:382
MetricsRegistryRegistrationHandle & operator=(bslmf::MovableRef< MetricsRegistryRegistrationHandle > original) BSLS_KEYWORD_NOEXCEPT
bool isRegistered() const
Definition bdlm_metricsregistry.h:391
MetricsRegistryRegistrationHandle()
Definition bdlm_metricsregistry.h:374
MetricsRegistryRegistrationHandle(bslmf::MovableRef< MetricsRegistryRegistrationHandle > original) BSLS_KEYWORD_NOEXCEPT
Definition bdlm_metricsregistry.h:199
MetricsAdapter::Callback Callback
Definition bdlm_metricsregistry.h:206
MetricsAdapter::CallbackHandle CallbackHandle
Definition bdlm_metricsregistry.h:207
bslma::Allocator * allocator() const
Return the allocator used by this object to supply memory.
BSLMF_NESTED_TRAIT_DECLARATION(MetricsRegistry, bslma::UsesBslmaAllocator)
void registerCollectionCallback(MetricsRegistryRegistrationHandle *result, const bdlm::MetricDescriptor &descriptor, const Callback &callback)
static MetricsRegistry & defaultInstance()
Return a non-const reference to the metrics registry singleton.
void removeMetricsAdapter(MetricsAdapter *adapter)
void setMetricsAdapter(MetricsAdapter *adapter)
MetricsRegistry(bslma::Allocator *basicAllocator=0)
int numRegisteredCollectionCallbacks() const
Return the number of registered metrics collection callbacks.
Forward declaration.
Definition bslstl_function.h:934
Definition bslstl_sharedptr.h:1830
Definition bslstl_sharedptr.h:3705
bool expired() const BSLS_KEYWORD_NOEXCEPT
Definition bslstl_sharedptr.h:5934
static void swap(T *a, T *b)
Definition bslalg_swaputil.h:194
Definition bslma_allocator.h:457
Definition bslmf_movableref.h:751
#define BSLS_IDENT(str)
Definition bsls_ident.h:195
#define BSLS_KEYWORD_DELETED
Definition bsls_keyword.h:609
#define BSLS_KEYWORD_NOEXCEPT
Definition bsls_keyword.h:632
Definition bdlm_instancecount.h:101
Definition bslma_usesbslmaallocator.h:343
Definition bslmf_movableref.h:791