Parallelism in CodeSonar

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.2p0

CONFIDENTIAL

CodeSecure Inc

General

Parallelism in CodeSonar

This section describes the availability and extent of parallelization within CodeSonar.

See also the Distributed Analysis section.

Hub
Build
Analysis
IPv4 Note

Hub Parallelism

The CodeSonar hub process runs in parallel, with a default maximum of 50 slave processes. (This limit, along with other hub process thresholds, can be changed from the HTTP tab of the Settings page.)

Build Parallelism

C/C++	The degree of parallelism involved in the CodeSonar build phase will mirror that of the underlying software build that CodeSonar is observing: if the underlying build invokes N compiler processes, then the CodeSonar project build will involve N processes of its own.
C#, Java	The degree of parallelism involved in the CodeSonar build phase will mirror the extent to which the observed cs-dotnet-scan/cs-java-scan commands are invoked in parallel.

To limit the total number of CodeSonar build phase processes to some maximum M, it suffices to specify that the underlying software build can have at most M processes. The mechanism for this will depend on the build system used.

For example, if the underlying software build is invoked by

make -j 4

then there will be at most four CodeSonar build phase processes at any time.

Analysis Parallelism

The analysis can run in serial mode or in parallel mode. Parallel mode provides some fault tolerance along with better time performance, but requires more working memory than serial mode.

The fault tolerance in parallel mode arises because the analysis master will create new slave processes to replace those that crash. If a unit of work (typically the analysis of a procedure, or a single hub request) fails too many times, the master will give up on that unit of work and move on to the next one.

The presence and degree of parallelism in the analysis process is controlled by configuration file parameters.

parse mode phase of analyze interval	The presence and degree of parallelism is controlled by PARSE_SLAVES and MAX_PARSE_SLAVES. The mechanism for automatically starting new parse slaves is determined by the REQUEST_REMOTE_PARSE_SLAVES setting.
analysis mode phase of analyze interval	The presence and degree of parallelism is controlled by ANALYSIS_SLAVES and MAX_ANALYSIS_SLAVES. The mechanism for automatically starting new analysis slaves is determined by the REQUEST_REMOTE_ANALYSIS_SLAVES setting.
daemon mode interval	The presence and degree of parallelism is controlled by DAEMON_SLAVES and MAX_DAEMON_SLAVES. Daemon mode behavior can be changed at any point by editing the value of DAEMON_SLAVES and restarting the analysis daemon. The mechanism for automatically starting new daemon slaves is determined by the REQUEST_REMOTE_DAEMON_SLAVES setting.

Related configuration variables for different phases do not have to have the same value. For example, {PARSE_SLAVES, ANALYSIS_SLAVES, DAEMON_SLAVES} do not have to have the same value.

The following table describes the effects of the available <phase>_SLAVES and REQUEST_REMOTE_<phase>_SLAVES combinations. That is:

PARSE_SLAVES and REQUEST_REMOTE_PARSE_SLAVES combinations
ANALYSIS_SLAVES and REQUEST_REMOTE_ANALYSIS_SLAVES combinations
DAEMON_SLAVES and REQUEST_REMOTE_DAEMON_SLAVES combinations

A different combination can be used for each phase.

<phase>_SLAVES Setting

REQUEST_REMOTE_<phase>_SLAVES Setting

Serial or Parallel?

Behavior

Serial

Yes or No

serial

ANALYSIS_SLAVES, DAEMON_SLAVES: There is only one process, with no slaves and no provision for manually attaching them.

"nearly serial"

PARSE_SLAVES: The master process will spawn front end processes as required to accomplish deep parsing. At most two processes will run at any given time: the master process plus at most one front end process. There is no provision for manually attaching slaves.

integer or Auto

Yes

parallel

The master will not start new slaves directly, but instead will request them from the hub. The precise setting of ANALYSIS_SLAVES (DAEMON_SLAVES, PARSE_SLAVES) has no effect in this case, although the setting of MAX_ANALYSIS_SLAVES (MAX_DAEMON_SLAVES, MAX_PARSE_SLAVES) is still important.
For full details, see Distributed Analysis.

parallel

The master will not automatically start any slaves, but will instead wait (indefinitely) for a manually started slave process.

parallel

The master will automatically start one slave. If the number of slaves subsequently reaches 0, the master will start a new slave.

This configuration is more fault-tolerant than serial mode, because the master can restart the slave if it unexpectedly fails. Running time is approximately equal to that for a serial analysis, but up to 512 MB more system memory is typically required.

n, with n>1

parallel

The master will automatically start slaves up to a limit of n slaves running simultaneously.

Auto

depends on resources

CodeSonar will compute a value M, where the computation depends on <phase>.

PARSE_SLAVES	M = min(Cores, max(0, (Mem / MEMORY_PER_PARSE_PROCESS) - 1))
ANALYSIS_SLAVES, DAEMON_SLAVES	M = min(Cores, max(0, (Mem / MEMORY_PER_ANALYSIS_PROCESS) - 1))

where Cores is the total number of logical cores on the machine and Mem is the amount of free physical memory.

If M≤1, the behavior is the same as described for <phase>_SLAVES=Serial.
If M>1, the analysis runs in parallel mode, with the master automatically starting slaves up to a limit of n slaves running simultaneously: equivalent to <phase>_SLAVES=M.

There are two separate parameters MEMORY_PER_PARSE_PROCESS/MEMORY_PER_ANALYSIS_PROCESS because parse slaves generally require more memory than analysis slaves or daemon slaves.

This computation works best when there are no competing demands for resources (including other CodeSonar analyses).

CodeSonar records its resolutions of Auto computations in the analysis log. Search for ANALYSIS_SLAVES=Auto (DAEMON_SLAVES=Auto, PARSE_SLAVES=Auto) to find the relevant log message.

The remainder of this section describes behavior and functionality in parallel mode.

The Master Process

The master process goes through three phases.

It starts out in parse mode to construct the CodeSonar project based on the information gathered during the preceding build interval.
- During this phase, we refer to the master process as the parse master, and its slaves as parse slaves.
Once the CodeSonar project is fully constructed, the process transitions to analysis mode to analyze the project.
- During this phase, we refer to the master process as the analysis master, and its slaves as analysis slaves.
Once analysis is completed, the process transitions to daemon mode to service requests from the hub.
- During this phase, we refer to the master process as the daemon master, and its slaves as daemon slaves.

Master process responsibilities are as follows.

Managing parse slaves during parse mode.
Performing analysis work during the serial-only states of analysis mode.
(See the Analysis States table to identify serial-only states.)
Managing analysis slaves during the parallelizable states of analysis mode.
(See the Analysis States table to identify parallelizable states.)
Communicating with the hub (via hub slaves) throughout parse mode and analysis mode (unless analysis is performed offline).
Managing daemon slaves during daemon mode.

The master listens on an address determined by the setting of the corresponding <phase>_MASTER_LISTEN_INTERFACE configuration parameter:

PARSE_MASTER_LISTEN_INTERFACE (parse mode)
ANALYSIS_MASTER_LISTEN_INTERFACE (analysis mode)
DAEMON_MASTER_LISTEN_INTERFACE (daemon mode).

These three parameters can be set to the same value, but this is not required.

<phase>_MASTER_LISTEN_INTERFACE Setting	Corresponding master process will listen on address...
set_host:set_port	set_host:set_port (if that address is not available, the master process will not run).
set_host	set_host:arb_port where arb_port is assigned by the operating system.
(no setting)	[::1]:arb_port if the master is local-requesting, [::]:arb_port if the master is remote-requesting, where arb_port is assigned by the operating system.

Once the master has started, the analysis log will contain a message that looks (something) like the following, and a corresponding message is added at when the master transitions to daemon mode.

Listening on [::1]:51614
Slaves can be started with the command:
codesonar slave [::1]:51614

Master ↔ Slave Communication

The socket type used for communication between the master process and its slaves is controlled by corresponding <phase>_MASTER_USE_TLS configuration file parameter.

PARSE_MASTER_USE_TLS (parse mode)
ANALYSIS_MASTER_USE_TLS (analysis mode)
DAEMON_MASTER_USE_TLS (daemon mode).

These three parameters can be set to the same value, but this is not required.

<phase>_MASTER_USE_TLS Setting	Socket type used for communication between corresponding master process and its slaves
Yes	TLS
No	Plain TCP
none	TLS if and only if HTTPS is enabled on the hub and the master's listening interface is not ::1; plain TCP otherwise. (Visit the hub's Configure HTTPS page to view or modify its HTTPS enabling status.)

If TLS sockets are used, the TLS layer uses the same 2 kilobit RSA key pairs as are used for master↔slave authentication.

Master ↔ Slave Authentication

When a slave process connects to the master process they perform mutual authentication (unless authentication has been specifically disabled, which will result in reduced security). This authentication takes place regardless of whether the master and slave are using TLS sockets for communication, but is vulnerable to snooping when TLS is not used.

Authentication is managed with 2 kilobit RSA key pairs. If the master and slave are using TLS sockets for communication, the same key pairs are used by the TLS layer.

Slave Processes

We refer to the analysis mode slave processes as follows.

parse slave	a parse mode slave process.
analysis slave	an analysis mode slave process.
daemon slave	a daemon mode slave process.

Slave processes perform individual units of work, as directed by the master process.

The typical unit of work depends on the mode.
- parse slave : parsing a single translation unit.
- analysis slave : the analysis of a single procedure or a single translation unit, depending on the analysis state.
- daemon slave : servicing a single web request from the hub.
In all cases a unit of work involves a mixture of I/O and CPU operations.
Experimental results suggest that analysis slaves and daemon slaves can use up to about 512MB. Parse slave requirements can vary wildly and there is no upper bound: if you are seeing a large number of cprocess processes using a lot of memory, increase the MEMORY_PER_PARSE_PROCESS setting.
Unwanted slave processes can be stopped using any system utility capable of killing processes. There is no serious penalty for doing this.

Slaves may experience various modes of failure:

network socket disconnection,
crashing,
the user or OS killing the slave process,
anything else that would cause a slave process to die or disconnect.

The setting of configuration file parameter UNIT_OF_WORK_RETRIES (default 3) specifies how many times a unit of work will be retried if it fails.

Automatically Started Slaves

The master process will automatically attempt to acquire new slaves if:

the analysis is running in parallel mode in the current phase (as described above), and
there is pending work, and
no slaves have been started in the past 5 seconds, and

the number of slaves currently connected is below the applicable limit, which depends on both the current phase and the requesting policy:

	remote-requesting	local-requesting
general form	the higher of <phase>_SLAVES and MAX_<phase>_SLAVES	<phase>_SLAVES
parse mode	the higher of PARSE_SLAVES and MAX_PARSE_SLAVES	PARSE_SLAVES
analysis mode	the higher of ANALYSIS_SLAVES and MAX_ANALYSIS_SLAVES	ANALYSIS_SLAVES
daemon mode	the higher of DAEMON_SLAVES and MAX_DAEMON_SLAVES	DAEMON_SLAVES,

(For computing these limits, <phase>_SLAVES is either the explicit value specified or the value computed for Auto.)

The mechanism used to automatically acquire slaves depends on whether the master is local-requesting or remote-requesting, as specified by the setting of the corresponding REQUEST_REMOTE_<phase>_SLAVES configuration parameter.

REQUEST_REMOTE_PARSE_SLAVES (parse mode)
REQUEST_REMOTE_ANALYSIS_SLAVES (analysis mode)
REQUEST_REMOTE_DAEMON_SLAVES (daemon mode)

For details, see Distributed Analysis.

Manually Started Slaves

You may wish to start slaves manually for various reasons, including manual load balancing or debugging plug-ins.

Security Note. While CodeSonar does provide support for manually starting parse/analysis/daemon slaves, it is important to note that this functionality involves setting environment variables that instruct the processes involved not to perform mutual authentication. This reduces security, so only set these environment variables if you trust every user with access to the address on which the master is listening. Depending on your hub interface and system configuration this may mean that you need to trust every user on the hub machine, or even every user on your network.

You can start a slave manually if:

master and slave are running the same version of CodeSonar, and
the analysis is running in parallel mode in the current phase (as described above), and
the master process has started listening, and
the slave has access to the address on which the master is listening, and

the number of slaves currently connected is below the limit imposed by the below the applicable limit, which depends on the current phase:

	upper bound on number of slaves
general form	the higher of <phase>_SLAVES and MAX_<phase>_SLAVES
parse mode	the higher of PARSE_SLAVES and MAX_PARSE_SLAVES
analysis mode	the higher of ANALYSIS_SLAVES and MAX_ANALYSIS_SLAVES
daemon mode	the higher of DAEMON_SLAVES and MAX_DAEMON_SLAVES

(For computing these limits, <phase>_SLAVES is either the explicit value specified or the value computed for Auto.)

and

there are sufficient system resources.
[Additionally, make sure you are satisfied that the security issues entailed are not of concern in your situation.]

To manually start a slave, proceed as follows. Note that there are two environment variables involved: CS_MASTER_WIDE_OPEN and CS_SLAVE_WIDE_OPEN.

Make sure that environment variable CS_MASTER_WIDE_OPEN is set to 1 in the environment in which the master process is running (parse master, analysis master, or daemon master, depending on which you are interested in).
This instructs the master process not to authenticate the slave process.
Note that the variable must be defined before the master process starts: if it is not set and the analysis is already running, you will not be able to manually attach any slaves.
Determine the address on which the master process is listening (not the hub address), by examining the analysis log to find the "Listening on..." message described above.
We will refer to this address as m_host:m_port.
Set REQUEST_REMOTE_<phase>_SLAVES=Yes. (REQUEST_REMOTE_PARSE_SLAVES, REQUEST_REMOTE_ANALYSIS_SLAVES, or REQUEST_REMOTE_DAEMON_SLAVES).
This allows the master process for the corresponding phase to send a request to the hub if it determines that it requires additional slaves.
If environment variable CS_SLAVE_WIDE_OPEN is not already set to 1 the environment in which you will run the slave process, define it now. This instructs the slave process not to authenticate the master process.
Run the following command.
codesonar slave m_host:m_port

A manually started slave process will run until the master process exits, unless it is killed by an appropriate system utility.

Questions

What is each process doing?

What is each process doing?

Use system utilities for viewing process command lines in order to see what each process is doing at any given time.

One or more of the following may work, depending on your system.

top Press c once top is running to see command lines
pstree -a
ps -x
cat /proc/123/cmdline

Ana fname indicates that a process is analyzing procedure fname(); IDLE indicates that it is doing nothing. IDLE usually happens because of dependences inherent in the analyzed code.

IPv4 Note

If your system does not support IPv6 addresses, use IPv4 to specify and identify addresses instead.

127.0.0.1 instead of ::1
0.0.0.0 instead of ::

To report problems with this documentation, please visit https://support.codesecure.com/.