Environment Variables

The following are environment variables supported by the main Binder system that is, libbinder, and thus everything that links against it.

Paths

These variables allow you to control where the Binder finds various parts of itself.

This is a ":"separated list of directories where the Package Manager should find packages. This variable must be set when running smooved, so that when it starts the package manager it will be able to find the Binder Shell component and other services it needs.

For example:

export BINDER_PACKAGE_PATH=~/openbinder/build/packages

Behavior

These variables control how the Binder system behaves and displays messages.

TEXT_OUTPUT_FORMAT

This variable allows you to control formatting of text sent to the standard output streams (bout, berr, etc). It contains a series of characters describing which formatting options to enable. Each character can be prefixed with a '!', indicating that option should be disbled. The available options are:

m: Multi-threaded output. The text stream will perform buffering of each thread writing into it, so that threads only write complete lines. This avoids the mixing together of partial lines when two threads are writing at the same time.
c: Colored output. Each line of output is colored by the thread that produced it. The color is selected based on the thread ID.
p: Add a prefix to the front of each line with the id of the process it came from.
t: Add a prefix to the front of each line with the id of the thread it came from.
w: Add a prefix to the front of each line with the timestamp when it was written.

For example, to enable multi-threaded colored output with a prefix showing the process but not the thread, you can do this:

export TEXT_OUTPUT_FORMAT='mcp!t'

BINDER_NO_CONTEXT_SECURITY

Setting this variable to a non-zero value disables the simple context permissions in smooved, so that any process can get access to any context. By default, processes only get access to the user context.

BINDER_SHOW_LOAD_UNLOAD

When set to a non-zero integer, the Binder will print out informative messages as it loads and unloads package code.

BINDER_SINGLE_PROCESS

When set to a non-zero integer, the Binder will attempt to keep code running in th same process, as much as possible. Currently this means that calling SContext::NewProcess() will return the local IProcess, unless the flag SContext::REQUIRE_REMOTE is used.

See Binder Process Model for more information on how the Binder manages processes.

It is important to understand the distinction between using BINDER_SINGLE_PROCESS=1 with the Binder kernel module available, and not having the kernel module at all:

With Kernel Module

When the kernel module is available, even if you set BINDER_SINGLE_PROCESS=1, the Binder runtime will still open the module and use it for various things. For example, it will still be used to manage the thread pool and schedule message delivery to SHandler objects.

In addition, smooved will still set itself as the SContext host. This means that you can still create other processes (such as with the bsh command), which can connect back to the root context and do IPC with other objects.

Without Kernel Module

When the kernel module is not available, there is no IPC available at all. For example, trying to run the bsh command will result in an error saying it could not find the root context, just as if smooved hadn't been running at all.

A more subtle distinction is that in this case the thread pool can't use the kernel module to schedule SHandler objects. Instead, it uses a different purely user-space implementation. This can lead to subtle differences in behavior between the two environments. (Assuming there aren't outright bugs in one implementation or the other.)

Debugging

These variables allow you to enable and control various debugging facilities provided by the Binder.

ATOM_DEBUG

Atom debugging is a tool for tracking SAtom reference count leaks. See SAtom Debugging for more information.

BINDER_IPC_PROFILE

Setting this variable to 1 will enable a profiler of the Binder's IPC mechanism, designed to help client programs discover "hot spots" where they are doing too much IPC.

In each process, the profiler makes a note of each outgoing IPC operation from that process and the stack crawl associated with it. After every X number of IPCs have happened, it prints a report of the total number of IPCs and the top N instigators of IPCs organized by stack crawl.

When the IPC profiler is enabled, you can use these additional environment variables to customize its behavior:

BINDER_IPC_PROFILE_DUMP_PERIOD is the number of IPC operations between each time the profiler statistics are displayed. The default value is 500.
BINDER_IPC_PROFILE_MAX_ITEMS is the maximum number of unique stack crawls display i.e., the top N callers to display. The default value is 10.
BINDER_IPC_PROFILE_STACK_DEPTH is the maximum depth that stack crawls can be. This is useful to tune what statistics are being displayed. For example, a smaller number will result in fewer bins because there are fewer possible paths into the IPC mechanism.
BINDER_IPC_PROFILE_SYMBOLS if non-zero, the default, will display symbol information in the stack crawl, making it much more verbose but easier to understand.

BINDER_PROCESS_WRAPPER

The variable supplies a "wrapper" command to run between caller of SContext::NewProcess() and the actual process it returns. This can be useful to insert xterm and/or gdb sessions into the process, for separating the output of multiple processes and easily catching crashes.

Using this variable usually requires creating a set of scripts and files to accomplish what you want in the wrapper process. The OpenBinder build system generates some scripts under build/scripts that create an xterm with gdb running inside of it. You can set BINDER_PROCESS_WRAPPER as follows to use these scripts:

export BINDER_PROCESS_WRAPPER=~/openbinder/build/scripts/process_wrapper.sh

LOCK_DEBUG

These variables control SLocker's debugging / deadlock detection code. This is enabled by default in debug builds. You can explicitly turn it off by setting LOCK_DEBUG=0. The LOCK_DEBUG_STACK_CRAWLS can likewise be set to 0 to not collect stack information as the deadlock detection runs this can allow you to run deadlock detection with less performance impact.

VECTOR_PROFILE

The VECTOR_PROFILE tools collects usage statistics on the SVector class. When enabled, it will print regular reports of the kinds of SVector operations that are being performed. The variable VECTOR_PROFILE_DUMP_PERIOD controls how often reports are printed; its default value is 1000.