VLink  2.3.0
A high-performance communication middleware
logger_plugin_interface.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 logger_plugin_interface.h
26  * @brief Abstract contract for shared-library logger backends loaded via the VLink @c Plugin system.
27  *
28  * @details
29  * A logger plugin is a shared library that exports a factory through @c VLINK_PLUGIN_DECLARE and
30  * embeds @c VLINK_PLUGIN_REGISTER inside its concrete subclass. At runtime the host application
31  * uses @c vlink::Plugin::load<LoggerPluginInterface> to construct an instance and forwards records
32  * accepted by the Logger file-channel level to its @c log method.
33  *
34  * @par Plugin contract
35  *
36  * | Hook | Direction | Contract |
37  * | ------------------------ | ---------------- | ------------------------------------------------ |
38  * | @c VLINK_PLUGIN_REGISTER | inside the class | Injects @c get_plugin_id() (ID = demangled name) |
39  * | @c VLINK_PLUGIN_DECLARE | translation unit | Exposes the factory and the version metadata |
40  * | @c init | host -> plugin | Called once after construction with the app name |
41  * | @c log | host -> plugin | Called per record after passing level filters |
42  * | @c flush | host -> plugin | Drains records accepted before the call |
43  * | Destructor | host -> plugin | Called when the host releases the plugin handle |
44  *
45  * @par Lifecycle
46  *
47  * @verbatim
48  * host plugin
49  * ---- ------
50  * Plugin::load<...> ----------> factory creates instance
51  * init(app_name) ----------> initialise backend
52  * log(level, msg) ----------> forward to backend (repeated)
53  * flush() ----------> drain accepted records
54  * Plugin destroy ----------> destroy instance
55  * @endverbatim
56  *
57  * @par Loading example
58  * @code
59  * vlink::Plugin plugin;
60  * auto backend = plugin.load<vlink::LoggerPluginInterface>("my_logger_plugin", 1, 0);
61  *
62  * if (backend) {
63  * backend->init("my_app");
64  * backend->log(vlink::Logger::kInfo, "Hello from plugin!");
65  * backend->flush();
66  * }
67  * @endcode
68  *
69  * @par Implementation example
70  * @code
71  * class MyLogger : public vlink::LoggerPluginInterface {
72  * public:
73  * bool init(std::string_view app_name) noexcept override { return true; }
74  * bool log(int level, std::string_view str) noexcept override { return write_to_backend(level, str); }
75  * void flush() noexcept override { flush_backend(); }
76  * };
77  * VLINK_PLUGIN_DECLARE(MyLogger, 1, 0)
78  * @endcode
79  *
80  * @note @p level mirrors @c vlink::Logger::Level values. All hooks are non-throwing plugin
81  * boundaries.
82  *
83  * @see Plugin, Logger
84  */
85 
86 #pragma once
87 
88 #include <string_view>
89 
90 #include "./plugin.h"
91 
92 namespace vlink {
93 
94 /**
95  * @class LoggerPluginInterface
96  * @brief Pure-virtual interface that every shared-library logger backend implements.
97  *
98  * @details
99  * Concrete subclasses use @c VLINK_PLUGIN_REGISTER internally to expose their factory and
100  * destructor functions to the @c Plugin loader. Instances are owned by the host application
101  * for the duration of the plugin handle. When selected through @c VLINK_LOG_PLUGIN, @c init runs
102  * after the host Logger is constructed and supports same-thread Logger re-entry, so implementations
103  * may create VLink communication nodes there. Other threads can continue logging to the console
104  * while initialisation is in progress, but their records are not sent to the plugin.
105  */
108 
109  protected:
111 
112  virtual ~LoggerPluginInterface() = default;
113 
114  public:
115  /**
116  * @brief Initialises the backend immediately after the plugin instance is constructed.
117  *
118  * @param app_name Calling application name; may inform log labels or file paths.
119  * @return @c true on success; @c false to indicate the plugin must not be used further.
120  */
121  virtual bool init(std::string_view app_name) noexcept = 0;
122 
123  /**
124  * @brief Writes a single record to the backend.
125  *
126  * @details
127  * Implementations should be non-blocking; @p str remains valid only for the duration of the
128  * call. The host may call this method concurrently. Logs emitted synchronously by this method
129  * or its dependencies are not forwarded back into the same plugin.
130  *
131  * @param level Severity using @c vlink::Logger::Level values.
132  * @param str Fully formatted record.
133  * @return @c true on success; @c false to indicate a write error. The global Logger does not
134  * retry or redirect a failed plugin write.
135  */
136  virtual bool log(int level, std::string_view str) noexcept = 0;
137 
138  /**
139  * @brief Drains records accepted by @c log before this call.
140  *
141  * @details
142  * Returns only after plugin-owned asynchronous work for earlier records has completed. A
143  * synchronous implementation can use the default no-op.
144  */
145  virtual void flush() noexcept {}
146 
147  private:
149 };
150 
151 } // namespace vlink
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174
Strongly-typed shared-library plugin loader with ID and version verification.
#define VLINK_PLUGIN_REGISTER(InterfaceType)
Declares a plugin's identity from the demangled name of its abstract interface.
Definition: plugin.h:359