Concurrency Models: Thread Entry Points

• Thread Entry Points
• Creating New Models
• Discovering Entry Points

Thread Entry Points

The functions that CodeSonar will treat as thread entry points can be divided into four categories:

• standard program entry functions
• functions specified with configuration parameters
• library functions modeled as thread entry points
• library functions modeled as signal handler entry points
  Signal handlers are essentially treated as a special kind of thread with the following additional properties.
  • Signal handlers cannot interrupt one another (but can interrupt normal threads).
  • Two signal handlers cannot execute concurrently.

Standard Program Entry Functions

CodeSonar always treats the following program entry functions as thread entry points:

• main()
• WinMain()

Functions Specified with Configuration Parameters

There are two relevant configuration parameters.

• FORCE_THREAD_ENTRY_NAMES : forces CodeSonar to treat specific functions as thread entry points.
• THREAD_ENTRY_METHOD_NAMES : for programs that use an object-oriented multithreading API, specifies which method on an object should be considered the "entry method" when the object (or a reference to it) is specified as a thread entry point.

Modeled Library Functions: Thread Entry Points

CodeSonar ships with library models that allow it to recognize a large number of thread entry point functions. A call to one of these functions will trigger a Thread Entry Point warning (when that class is enabled). Some examples are listed in the following table

Modeled Library Functions: Signal Handler Entry Points

CodeSonar ships with library models that allow it to identify functions such as libc signal() as signal handler entry points. A call to one of these functions will trigger a Signal Handler Entry Point warning (when that class is enabled).

Creating New Models

If you are authoring a model for a function that specifies a thread entry point or signal handler entry point, it is usually best to have the model call the already-modeled function that is most similar. This will ensure that CodeSonar correctly treats the function as specifying an entry point, and includes it in the appropriate checks.

If no existing model is appropriate, write your model using the extension functions provided. In particular, your model should call one of the following functions.

See the function documentation for annotated examples.

Discovering Entry Points

CodeSonar will identify thread entry points if the Data Race warning class is enabled.

The two most likely causes of a failure in entry point discovery are time limits and library modeling issues. If you suspect that CodeSonar has not discovered all the thread entry points in your project:

1. Open the analysis log.
2. Search for the text
   Thread entry points:
   Below that heading is a list of the procedures and methods that have been identified as thread entry points, along with various other information.
3. Check the list of identified thread entry points.
   • If one or more of your project's thread entry points are missing from the list, you will need to take some additional steps, as outlined below.

Alternatively, enable warning class Thread Entry Point, so that CodeSonar issues a warning at every identified thread entry point.

For example, the following simple program has two thread entry points: main() and entry_f().

#include <pthread.h>

int x;

void *entry_f( void *a ){
    x = 5;
    return a;
}

int main( int argc, char** argv ){
    pthread_t t;
    pthread_create( &t, NULL, entry_f, NULL );
    x = 4;
    return argc;
}

CodeSonar identifies both entry points:

• The program entry function (main() in this case) is always a thread entry point.
• The library model for pthread_create() identifies it as a function that specifies a thread entry point, and it is called with entry point argument entry_f.

The relevant part of the analysis log looks (something) like the following.

[...]
Thread entry points:
Thread entry point: entry_f
  lockset map: 0x7fffec1b1318

           [MAK_READ:global_locks #locks: 0 #path_dags: 1 ls:{ }]
           [MAK_WRITE:x #locks: 0 #path_dags: 1 ls:{ }]
           [MAK_WRITE:global_locks-&next #locks: 0 #path_dags: 1 ls:{ }]
             
Thread entry point: main
  lockset map: 0x7ffff7efcbb0

           [MAK_WRITE:x #locks: 0 #path_dags: 1 ls:{ }]
[...]
  

Time limits

Enabling data race detection increases the amount of information that the CodeSonar analysis must gather and store. This can cause various steps in the analysis process to take more time. In some cases, they can take so long that analysis time limits expire, causing CodeSonar to drop data that is needed to identify thread entry points properly. To maintain high precision and ensure that thread entry points are discovered, you may need to increase some of these time limits.

The time limits that are most important to thread entry point discovery are governed by configuration file parameters:

• TIME_LIMIT_INTER_CLASSIFY
• TIME_LIMIT_INTRA_CLASSIFY
• TIME_LIMIT_INTRA_EXPLORE
• TIME_LIMIT_PROP_EXHAUSTIVE
• TIME_LIMIT_RESOLVE

To determine whether time limit expiration is affecting thread entry point discovery for your project:

1. Open the analysis log.
2. Search for the text
   TIME_LIMIT_
   This will find all the reports of configured time limits expiring.
3. If you see many expirations of any of the time limits that are important to thread entry point discovery:
   1. increase the corresponding settings in your general project configuration file, then
   2. run the analysis again.

Library modeling issues

If CodeSonar did not discover any thread entry points (or only main()), there is probably a library modeling issue.

A critical element of thread discovery is identifying thread creation procedures, including understanding how their arguments are used to specify a thread starting point. This requires that library models be provided for thread creation procedures. If a model for your thread creation procedure is not shipped with CodeSonar, you will need to create a model or directly modify your code.

Example

It is relatively common for large code bases to include their own thread entry point wrappers. These wrappers make it hard for CodeSonar to identify true thread entry points, and are themselves candidates for modeling.

Here is a small example:

/* Code Excerpt 1: User code with wrappers. */

/* underlying API function: real_thread_create()
 * thread creation wrapper: thread_create_wrapper()
 * thread entry point: user_thread_entry_point()
 * thread entry wrapper: thread_entry_wrapper()

typedef struct{
   function_pointer f;
   data_pointer d;
} thread_entry_closure;

void thread_entry_wrapper( thread_entry_closure *c ){
   /* ... additional thread setup code */
   c->f( c->d );
   /* ... additional thread teardown code */
}

void thread_create_wrapper( function_pointer fp, data_pointer dp )
{
  thread_entry_closure c = { fp, dp };
  real_thread_create( thread_entry_wrapper, &c );
}

void user_thread_entry_point( data_pointer d ){
   /* ... code that runs in a separate thread */
}

void other_user_code( void ){
  thread_create_wrapper( user_thread_entry_point, xyz );
}

To handle this kind of code, you need to inform CodeSonar that

• the thread creation wrapper (thread_create_wrapper() in the example above) is effectively a thread creation function, and
• the fp parameter to thread_create_wrapper() is a thread entry point.

You can do this either by creating a library model for thread_create_wrapper(), or by directly modifying the source code:

/* Code Excerpt 2: Direct source modification for Code Excerpt 1. */

#ifdef __CODESONAR__
#include <stdlib.h>
#include "csonar.h"
#endif

void thread_create_wrapper( function_pointer fp, data_pointer dp )
{
#ifdef __CODESONAR__
   csonar_thread_create( *((csonar_thread_entry_fn_t*)&fp), dp );
#endif
   thread_entry_closure c = { fp, dp };
   real_thread_create( thread_entry_wrapper, &c );
}