/src/logging-log4cxx/src/main/include/log4cxx/asyncappender.h
Line | Count | Source (jump to first uncovered line) |
1 | | /* |
2 | | * Licensed to the Apache Software Foundation (ASF) under one or more |
3 | | * contributor license agreements. See the NOTICE file distributed with |
4 | | * this work for additional information regarding copyright ownership. |
5 | | * The ASF licenses this file to You under the Apache License, Version 2.0 |
6 | | * (the "License"); you may not use this file except in compliance with |
7 | | * the License. You may obtain a copy of the License at |
8 | | * |
9 | | * http://www.apache.org/licenses/LICENSE-2.0 |
10 | | * |
11 | | * Unless required by applicable law or agreed to in writing, software |
12 | | * distributed under the License is distributed on an "AS IS" BASIS, |
13 | | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
14 | | * See the License for the specific language governing permissions and |
15 | | * limitations under the License. |
16 | | */ |
17 | | |
18 | | #ifndef _LOG4CXX_ASYNC_APPENDER_H |
19 | | #define _LOG4CXX_ASYNC_APPENDER_H |
20 | | |
21 | | #include <log4cxx/appenderskeleton.h> |
22 | | #include <log4cxx/helpers/appenderattachableimpl.h> |
23 | | #include <log4cxx/spi/loggingevent.h> |
24 | | |
25 | | namespace LOG4CXX_NS |
26 | | { |
27 | | LOG4CXX_LIST_DEF(LoggingEventList, spi::LoggingEventPtr); |
28 | | |
29 | | /** |
30 | | The AsyncAppender decouples logging event creation from output |
31 | | by processing log events asynchronously. |
32 | | |
33 | | The AsyncAppender stores the logging event in a bounded buffer |
34 | | and then returns control to the application. |
35 | | A separate thread forwards events to the attached appender(s). |
36 | | |
37 | | <b>Important notes:</b> |
38 | | - Your application must call LogManager::shutdown when it exits |
39 | | to prevent undefined behaviour when using this appender. |
40 | | - Runtime configuration requires an XML configuration file |
41 | | (see the example below). |
42 | | |
43 | | This appender is useful when outputting to a slow event sink, |
44 | | for example, a remote SMTP server or a database. |
45 | | Attaching a FileAppender to AsyncAppender |
46 | | to reduce logging overhead is not recommended |
47 | | as the inter-thread communication overhead |
48 | | can exceed the time to write directly to a file. |
49 | | |
50 | | You can attach multiple appenders to an AsyncAppender by: |
51 | | - calling AsyncAppender::addAppender repeatedly when progammatically configuring Log4cxx. |
52 | | - adding multiple <b>appender-ref</b> elements |
53 | | to the <b>appender class="AsyncAppender"</b> element |
54 | | when using runtime configuration. |
55 | | |
56 | | Here is a sample configuration file: |
57 | | \include async-example.xml |
58 | | |
59 | | ### Configurable properties |
60 | | |
61 | | When the application produces logging events faster |
62 | | than the background thread is able to process, |
63 | | the bounded buffer can become full. |
64 | | In this situation AsyncAppender will either |
65 | | block until the bounded buffer has a free slot or |
66 | | discard the event. |
67 | | The <b>Blocking</b> property controls which behaviour is used. |
68 | | When events are discarded, |
69 | | the logged output will indicate this |
70 | | with a log message prefixed with <i>Discarded</i>. |
71 | | The output may contain one <i>Discarded</i> message per logger name, |
72 | | the logging event of the highest level for each logger |
73 | | whose events have been discarded. |
74 | | |
75 | | To determine whether the application produces logging events faster |
76 | | than the background thread is able to process, enable [Log4cxx internal debugging](internal-debugging.html). |
77 | | The AsyncAppender will output a histogram of queue length frequencies when closed. |
78 | | |
79 | | See AsyncAppender::setOption for details. |
80 | | |
81 | | */ |
82 | | class LOG4CXX_EXPORT AsyncAppender : |
83 | | public virtual spi::AppenderAttachable, |
84 | | public virtual AppenderSkeleton |
85 | | { |
86 | | protected: |
87 | | struct AsyncAppenderPriv; |
88 | | |
89 | | public: |
90 | | DECLARE_LOG4CXX_OBJECT(AsyncAppender) |
91 | 0 | BEGIN_LOG4CXX_CAST_MAP() |
92 | 0 | LOG4CXX_CAST_ENTRY(AsyncAppender) |
93 | 0 | LOG4CXX_CAST_ENTRY_CHAIN(AppenderSkeleton) |
94 | 0 | LOG4CXX_CAST_ENTRY(spi::AppenderAttachable) |
95 | 0 | END_LOG4CXX_CAST_MAP() |
96 | | |
97 | | /** |
98 | | * Create new instance. |
99 | | */ |
100 | | AsyncAppender(); |
101 | | |
102 | | /** |
103 | | * Destructor. |
104 | | */ |
105 | | virtual ~AsyncAppender(); |
106 | | |
107 | | /** |
108 | | * Ensure \c newAppender receives any logging event |
109 | | * added to this appender. |
110 | | * |
111 | | * @param newAppender appender to add, may not be null. |
112 | | */ |
113 | | void addAppender(const AppenderPtr newAppender) override; |
114 | | |
115 | | void doAppend(const spi::LoggingEventPtr& event, |
116 | | helpers::Pool& pool1) override; |
117 | | |
118 | | void append(const spi::LoggingEventPtr& event, helpers::Pool& p) override; |
119 | | |
120 | | /** |
121 | | Close this <code>AsyncAppender</code> by interrupting the |
122 | | dispatcher thread which will process all pending events before |
123 | | exiting. |
124 | | */ |
125 | | void close() override; |
126 | | |
127 | | /** |
128 | | * Get iterator over attached appenders. |
129 | | * @return list of all attached appenders. |
130 | | */ |
131 | | AppenderList getAllAppenders() const override; |
132 | | |
133 | | /** |
134 | | * Get appender by name. |
135 | | * |
136 | | * @param name name, may not be null. |
137 | | * @return matching appender or null. |
138 | | */ |
139 | | AppenderPtr getAppender(const LogString& name) const override; |
140 | | |
141 | | /** |
142 | | * The current value of the (unused) <b>LocationInfo</b> option. |
143 | | */ |
144 | | bool getLocationInfo() const; |
145 | | /** |
146 | | * Determines if specified appender is attached. |
147 | | * @param appender appender. |
148 | | * @return true if attached. |
149 | | */ |
150 | | bool isAttached(const AppenderPtr appender) const override; |
151 | | |
152 | | bool requiresLayout() const override; |
153 | | |
154 | | /** |
155 | | * Removes and closes all attached appenders. |
156 | | */ |
157 | | void removeAllAppenders() override; |
158 | | |
159 | | /** |
160 | | * Removes an appender. |
161 | | * @param appender appender to remove. |
162 | | */ |
163 | | void removeAppender(const AppenderPtr appender) override; |
164 | | /** |
165 | | * Remove appender by name. |
166 | | * @param name name. |
167 | | */ |
168 | | void removeAppender(const LogString& name) override; |
169 | | |
170 | | /** |
171 | | * Replace \c oldAppender with \c newAppender. |
172 | | * @return true if oldAppender was replaced with newAppender. |
173 | | */ |
174 | | bool replaceAppender(const AppenderPtr& oldAppender, const AppenderPtr& newAppender) LOG4CXX_16_VIRTUAL_SPECIFIER; |
175 | | |
176 | | /** |
177 | | * Replace any previously added appenders with \c newList. |
178 | | */ |
179 | | void replaceAppenders(const AppenderList& newList) LOG4CXX_16_VIRTUAL_SPECIFIER; |
180 | | |
181 | | /** |
182 | | * The <b>LocationInfo</b> attribute is provided for compatibility |
183 | | * with log4j and has no effect on the log output. |
184 | | * @param flag new value. |
185 | | */ |
186 | | void setLocationInfo(bool flag); |
187 | | |
188 | | /** |
189 | | * The <b>BufferSize</b> option takes a non-negative integer value. |
190 | | * This integer value determines the maximum size of the bounded |
191 | | * buffer. |
192 | | * */ |
193 | | void setBufferSize(int size); |
194 | | |
195 | | /** |
196 | | * Gets the current buffer size. |
197 | | * @return the current value of the <b>BufferSize</b> option. |
198 | | */ |
199 | | int getBufferSize() const; |
200 | | |
201 | | /** |
202 | | * Sets whether appender should wait if there is no |
203 | | * space available in the event buffer or immediately return. |
204 | | * |
205 | | * @param value true if appender should wait until available space in buffer. |
206 | | */ |
207 | | void setBlocking(bool value); |
208 | | |
209 | | /** |
210 | | * Gets whether appender should block calling thread when buffer is full. |
211 | | * If false, messages will be counted by logger and a summary |
212 | | * message appended after the contents of the buffer have been appended. |
213 | | * |
214 | | * @return true if calling thread will be blocked when buffer is full. |
215 | | */ |
216 | | bool getBlocking() const; |
217 | | |
218 | | |
219 | | /** |
220 | | \copybrief AppenderSkeleton::setOption() |
221 | | |
222 | | Supported options | Supported values | Default value | |
223 | | -------------- | ---------------- | --------------- | |
224 | | BufferSize | int | 128 | |
225 | | Blocking | True,False | True | |
226 | | |
227 | | \sa AppenderSkeleton::setOption() |
228 | | */ |
229 | | void setOption(const LogString& option, const LogString& value) override; |
230 | | |
231 | | |
232 | | private: |
233 | | AsyncAppender(const AsyncAppender&); |
234 | | AsyncAppender& operator=(const AsyncAppender&); |
235 | | |
236 | | /** |
237 | | * Dispatch routine. |
238 | | */ |
239 | | void dispatch(); |
240 | | |
241 | | }; // class AsyncAppender |
242 | | LOG4CXX_PTR_DEF(AsyncAppender); |
243 | | } // namespace log4cxx |
244 | | |
245 | | #endif// _LOG4CXX_ASYNC_APPENDER_H |
246 | | |