VLink  2.3.0
A high-performance communication middleware
discovery_reporter.h
浏览该文件的文档.
1 /*
2  * Copyright (C) 2026 by Thun Lu. All rights reserved.
3  * Author: Thun Lu <thun.lu@zohomail.cn>
4  * Repo: https://github.com/thun-res/vlink
5  * _ __ __ _ __
6  * | | / / / / (_) ____ / /__
7  * | | / / / / / / / __ \ / //_/
8  * | |/ / / /___ / / / / / / / ,<
9  * |___/ /_____/ /_/ /_/ /_/ /_/|_|
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 
24 /**
25  * @file discovery_reporter.h
26  * @brief Process-wide discovery broadcaster that advertises live VLink endpoints.
27  *
28  * @details
29  * @c DiscoveryReporter is the announce side of the VLink discovery subsystem. It runs
30  * on a private @c MessageLoop and emits periodic UDP multicast (default @c 239.255.0.100)
31  * payloads that describe every @c NodeImpl currently registered in the process: their
32  * URLs, communication kind, host name, PID, application name and an optional CPU usage
33  * sample. Listeners on the network -- typically @c DiscoveryViewer instances or the
34  * @c vlink-cli tool -- consume those payloads to rebuild a live endpoint topology.
35  *
36  * Discovery flow:
37  *
38  * @verbatim
39  * NodeImpl::init_ext() ----> DiscoveryReporter::add()
40  * |
41  * v
42  * +-----------+ periodic timer UDP multicast
43  * | loop | ------------------> 239.255.0.100
44  * +-----------+
45  * ^ |
46  * | v
47  * NodeImpl::deinit_ext() ----> remove() DiscoveryViewer
48  * @endverbatim
49  *
50  * The process reporter is owned by the VLink runtime and is not exposed as a public
51  * singleton. @c add() and @c remove() are invoked automatically by
52  * @c NodeImpl::init_ext() / @c NodeImpl::deinit_ext(); normal user code should rarely
53  * touch this class directly.
54  *
55  * @par Example
56  * @code
57  * // Disable discovery entirely:
58  * // export VLINK_DISCOVER_DISABLE=1
59  *
60  * // Advanced tooling may construct an explicit reporter instance.
61  * vlink::DiscoveryReporter reporter;
62  * reporter.async_run();
63  * @endcode
64  *
65  * @note Discovery rides on a dedicated UDP socket and is independent of any VLink
66  * transport backend (intra/shm/dds/zenoh/...). Set @c VLINK_DISCOVER_DISABLE=1 to
67  * disable the runtime-owned reporter for a given process. Each report is multicast once
68  * through the interface chosen by the system route; @c VLINK_DISCOVER_IP (comma or space
69  * separated addresses) sends one report per listed address,
70  * @c VLINK_DISCOVER_NATIVE=1 limits it to loopback and @c VLINK_DISCOVER_DOMAIN shifts the
71  * discovery port to isolate the channel.
72  */
73 
74 #pragma once
75 
76 #include <memory>
77 #include <string>
78 
79 #include "../base/macros.h"
80 #include "../base/message_loop.h"
81 
82 namespace vlink {
83 
84 class NodeImpl;
85 
86 /**
87  * @class DiscoveryReporter
88  * @brief Periodic multicast broadcaster of the process's active VLink endpoints.
89  */
91  public:
92  /**
93  * @brief Builds the reporter, opens its UDP socket and arms the periodic timer.
94  *
95  * @details
96  * The @c MessageLoop is left idle; callers are responsible for calling @c async_run().
97  * The runtime-owned process reporter does this automatically.
98  */
100 
101  /**
102  * @brief Stops the loop and releases the UDP socket.
103  *
104  * @details
105  * An offline notification is only emitted when offline reporting is compiled in; the
106  * default build omits it.
107  */
108  ~DiscoveryReporter() override;
109 
110  /**
111  * @brief Registers a node so that subsequent broadcasts include it.
112  *
113  * @details
114  * Invoked automatically by @c NodeImpl::init_ext().
115  *
116  * @param node Node endpoint to track.
117  */
118  void add(NodeImpl* node);
119 
120  /**
121  * @brief Unregisters a node so that subsequent broadcasts exclude it.
122  *
123  * @details
124  * Invoked automatically by @c NodeImpl::deinit_ext().
125  *
126  * @param node Node endpoint to drop.
127  */
128  void remove(NodeImpl* node);
129 
130  protected:
131  size_t get_max_task_count() const override;
132 
133  uint32_t get_max_elapsed_time() const override;
134 
135  void on_begin() override;
136 
137  void on_end() override;
138 
139  private:
140  void rebuild_message();
141 
142  void send_report();
143 
144  void send_offline();
145 
146  static const std::string& get_host_name();
147 
148  static const std::string& get_app_name();
149 
150  struct Impl;
151  std::unique_ptr<Impl> impl_;
152 
154 };
155 
156 } // namespace vlink
#define VLINK_EXPORT
Definition: macros.h:81
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174