Coverage Report

Created: 2025-08-24 06:21

/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