Threading

Table of Contents

• Unexpected Exit
• Signal Handling with Log4cxx
  • Configuring Thread

Log4cxx is designed to be thread-safe under under normal usage. This means that logging itself is always thread-safe, however there are certain circumstances that can cause threading issues with Log4cxx.

Unexpected Exit

In multithreaded applications, it is possible to call exit() from any thread in the application. When this happens, other threads in the application may continue to run and attempt to log information. As of version 12 of Log4cxx, this should not cause the library to crash.

We recommend that a graceful exit be performed whenever possible, and that all threads be terminated properly before returning from main().

See LOGCXX-322 for more information.

Signal Handling with Log4cxx

Under certain configurations, Log4cxx may create new threads in order to do tasks(e.g. network comms, other async operations). On Linux/POSIX systems, this can lead to undesirable signal delivery, as signals can be delivered to any thread in the process. This can be most clearly seen if your application uses the sigwait(3) system call, as the thread that calls sigwait may not be the thread that actually gets the signal. By default, Log4cxx configures itself to block all signals to new threads that it creates on Linux/POSIX systems. See the section on configuring for more details on how to configure.

There are three main ways to handle signals coming to your process. All of these ways of handling signals are supported by Log4cxx in order to provide flexibility to users of the library. These three ways are:

1. Write to a file descriptor in a signal handler, notifying your main event loop of a signal. If you use Qt, their documentation has information on this method of handling a signal.
2. (Linux-only) Use signalfd(2) to create a file descriptor that notifies you of a signal. This is a special case of (1).
3. Block signals in newly created threads, ensuring that signals can only be sent to threads of your choosing.

If you need to use option #3(for example, because you are using sigwait), Log4cxx provides a mechanism for defining methods to be called at two main points in the lifecycle of a thread:

1. Just before the thread starts
2. Just after the thread starts

These two points are intended to let client code determine how best to start threads. Log4cxx provides a basic implementation of these for POSIX in order to block signals to the new threads that it creates.

Once a new thread is created, there is also a callback function that lets client code do operations on the thread directly. A sample method in Log4cxx has a callback to name the thread in order to make debugging nicer.

In order to use these callback functions, use the ThreadUtility class. You can configure the ThreadUtility class in several different ways by using the ThreadUtility::configure method with several pre-defined configurations. In the event that you need special signal handling, you can implement your own functions, and use the ThreadUtility::configureFuncs method in order to customize exactly what happens.

Configuring Thread

To tell Log4cxx what to do by default when starting a new thread, the enum ThreadConfigurationType may be used to configure the library appropriately. By default, all signals on POSIX systems will be blocked to ensure that other threads do not get signals.

To change this default, a simple change to your configuration files may be done.

Example to disable the automatic signal blocking with XML configuration:

<log4j:configuration threadConfiguration="NoConfiguration">
...
</log4j:configuration>

Example to disable the automatic signal blocking with properties configuration:

log4j.threadConfiguration=NoConfiguration