Flow-IPC 1.0.0
Flow-IPC project: Full implementation reference.
blob_stream_mq.hpp
Go to the documentation of this file.
1/* Flow-IPC: Core
2 * Copyright 2023 Akamai Technologies, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the
5 * "License"); you may not use this file except in
6 * compliance with the License. You may obtain a copy
7 * of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in
12 * writing, software distributed under the License is
13 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
14 * CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing
16 * permissions and limitations under the License. */
17
18/// @file
19#pragma once
20
22
23namespace ipc::transport
24{
25
26// Types.
27
28/**
29 * Base of Blob_stream_mq_sender and Blob_stream_mq_receiver containing certain `static` facilities, particularly
30 * for post-abort persistent resource cleanup. As of this writing this type stores no data.
31 *
32 * @tparam Persistent_mq_handle
33 * See Persistent_mq_handle concept doc header.
34 */
35template<typename Persistent_mq_handle>
37{
38public:
39 // Methods.
40
41 /**
42 * Removes the Blob_stream_mq_sender and/or Blob_stream_mq_receiver persistent resources associated with
43 * a Persistent_mq_handle with the given name. Please see Cleanup in Blob_stream_mq_sender doc header for
44 * context; and note it applies equally to Blob_stream_mq_receiver. In short: Those classes gracefully
45 * clean up by themselves, via their dtors; but an abort (or two) may prevent this from occurring -- in which
46 * case one should do one of the following:
47 * - If the name of the potentially-leaked MQ is known: Call this function, remove_persistent().
48 * - If not, but you used a name-prefix-based scheme: Call
49 * `remove_each_persistent_with_name_prefix<Blob_stream_mq_base>()`, providing the applicable name prefix.
50 * It will invoke remove_persistent() (and for_each_persistent()) internally as needed.
51 *
52 * Trying to remove a non-existent name *is* an error; but typically one should ignore any error, since the
53 * function is meant for best-effort cleanup in case a leak occurred earlier due to abort(s).
54 *
55 * Logs INFO message.
56 *
57 * ### Rationale ###
58 * Why does this exist, when Persistent_mq_handle::remove_persistent() is available? Answer:
59 * Blob_stream_mq_base sub-classes require certain internal resources (tiny SHM pools as of this writing)
60 * to ensure a single sender and single receiver per MQ (a limitation not imposed by the lower-level
61 * Persistent_mq_handle construct).
62 *
63 * @param logger_ptr
64 * Logger to use for subsequently logging.
65 * @param name
66 * Absolute name at which the persistent MQ (fed to Blob_stream_mq_sender and/or
67 * Blob_stream_mq_receiver ctor) lives.
68 * @param err_code
69 * See `flow::Error_code` docs for error reporting semantics. #Error_code generated:
70 * various.
71 */
72 static void remove_persistent(flow::log::Logger* logger_ptr, const Shared_name& name,
73 Error_code* err_code = 0);
74
75 /**
76 * Forwards to Persistent_mq_handle::for_each_persistent(). In practice this exists merely to enable
77 * templates remove_each_persistent_with_name_prefix() and remove_each_persistent_if() to work with
78 * Blob_stream_mq_base.
79 *
80 * @tparam Handle_name_func
81 * See Persistent_mq_handle::for_each_persistent().
82 * @param handle_name_func
83 * See Persistent_mq_handle::for_each_persistent().
84 */
85 template<typename Handle_name_func>
86 static void for_each_persistent(const Handle_name_func& handle_name_func);
87}; // class Blob_stream_mq_base
88
89// Template implementations.
90
91template<typename Persistent_mq_handle>
92void Blob_stream_mq_base<Persistent_mq_handle>::remove_persistent(flow::log::Logger* logger_ptr, // Static.
93 const Shared_name& name, Error_code* err_code)
94{
96}
97
98template<typename Persistent_mq_handle>
99template<typename Handle_name_func>
100void // Static.
102{
104}
105
106} // namespace ipc::transport
static void for_each_persistent(const Handle_name_func &handle_name_func)
See Blob_stream_mq_base counterpart.
static void remove_persistent(flow::log::Logger *logger_ptr, const Shared_name &name, Error_code *err_code)
See Blob_stream_mq_base counterpart.
Base of Blob_stream_mq_sender and Blob_stream_mq_receiver containing certain static facilities,...
static void for_each_persistent(const Handle_name_func &handle_name_func)
Forwards to Persistent_mq_handle::for_each_persistent().
static void remove_persistent(flow::log::Logger *logger_ptr, const Shared_name &name, Error_code *err_code=0)
Removes the Blob_stream_mq_sender and/or Blob_stream_mq_receiver persistent resources associated with...
String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...
Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...
flow::Error_code Error_code
Short-hand for flow::Error_code which is very common.
Definition: common.hpp:297