Documentation
Rate This Document
Findability
Accuracy
Completeness
Readability
SubmitClose

Custom Lock Filtering

You can add the -cf/--config-file parameter next to the devkit advisor dr-check command to skip dynamic memory consistency check for specified custom locks.

To add the -cf/--config-file parameter, specify the JSON configuration file and write the custom lock and unlock functions to be filtered in the file.

Example of Filtering Custom Locks

In this example, the configuration file is edited to filter custom locks. After dynamic memory consistency check is performed, custom locks are filtered.

  1. Compile the source file to generate an executable binary file. The following example describes how to add a lock for a user-defined class. Add lock and unlock functions to the configuration file specified by -cf when needed.
    1
    g++ test.cpp -o test -g -lpthread
    The content of the test.cpp file is as follows:
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
    #include <atomic>
#include <iostream>
#include <pthread.h>

class my_custom_spinlock{
    std::atomic_flag is_locked ={false};

public:
  void lock(){
      while (is_locked.test_and_set(std::memory_order_acquire)){}
  }

  void unlock (){
      is_locked.clear (std::memory_order_release);
  }
};

int data_race = 0;

my_custom_spinlock spinlock;

void* first_thread(void* arg){
    spinlock.lock();
    data_race = 5;
    spinlock.unlock();
    return 0;
}
void* second_thread(void* arg){
    spinlock.lock();
    data_race = 3;

    spinlock.unlock();
    return 0;
}

int main(int argc, char *argv[])
{
    pthread_t thr1, thr2;
    pthread_create(&thr1, NULL, first_thread, NULL);
    pthread_create(&thr2, NULL, second_thread, NULL);
    pthread_join(thr1, NULL);
    pthread_join(thr2, NULL);
    for(int i = 1; i <argc; ++i){
        std::cout<< argv[i] << std::endl;
    }

    std::cout<< data_race << std::endl;
    return 0;
}
  2. Perform dynamic memory consistency check. Replace the example ELF file path (/home/advisor/test) with the actual one.
    devkit advisor dr-check -f /home/advisor/test

    The following information in bold indicates that two lines of code need to be modified.

    Executing dynamic memory consistency check task, please wait...
The pid of the memtracer process is 1459201
Scanned time: 2025/05/11 07:06:12

Configuration:
    ELF filepath: /home/advisor/test
    Scan source code path: /home/testcase/project
    Generate report path: /home/DevKit_Software
    Generate report type: all
    Task Timeout Interval: The timeout period is not set.
    Log level: info

Summary:
There are 2 recommended code lines to modify.

For the details information on multi-thread races, please check:
    /home/DevKit_Software/dr-check_test_20250511070612_124d.json
    /home/DevKit_Software/dr-check_test_20250511070612_124d.html
    /home/DevKit_Software/dr-check_test_20250511070612_124d.csv
  3. To filter my_custom_spinlock, create the config.json configuration file and write the lock and unlock functions to be filtered into the configuration file.
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
    {
    "receive": [
        {
            "id_arg": 0,
            "name":"my_custom_spinlock::lock(*)",
            "shared": false,
            "success": "always"
        }
    ],
    "send": [
        {
            "id_arg": 0,
            "name": "my_custom_spinlock::unlock(*)"
        }
    ]
}

    The receive list is a custom lock function, indicating the function that waits for resources (similar to the principle of pthread_mutex_lock). The send list is a custom unlock function, indicating the function that releases resources (similar to the principle of pthread_mutex_unlock).

    Common configuration options of lock and unlock functions:

    • id_arg: indicates the index that represents the lock object in the parameter list of the lock or unlock function. Generally, the lock object is a pointer.
    • name: indicates the full name of the lock or unlock function. In C++, the function name is in the format of class::function_name(*). In C, the function name is in the format of function_name. You can use an asterisk (*) to match or skip any character.

    Dedicated configuration options of a lock function:

    • shared: indicates whether the object operated by the function is a read lock. The value is false or true and defaults to false. For a read lock, in the context of a read/write lock, the value of the shared field is true.
    • success: defines the return value that indicates a successful lock. The value is always, zero, or non_zero and defaults always. For a custom try_lock function, set this field based on the 0 return value (corresponding to zero) or another value (corresponding to non_zero).
  4. Perform dynamic memory consistency check again.
    devkit advisor dr-check -f /home/advisor/test -cf /home/testcase/config.json

    /home/testcase/config.json: This JSON configuration file specifies the custom lock not included in dynamic memory consistency check. Modify the file based on your requirements.

    The following information in bold indicates that no code lines need to be modified when filtering custom locks.

    Executing dynamic memory consistency check task, please wait...
The pid of the memtracer process is 1459201
Scanned time: 2025/05/12 07:08:15

Configuration:
    ELF filepath: /home/advisor/test
    Scan source code path: /home/testcase/project
    Generate report path: /home/DevKit_Software
    Generate report type: all
    Task Timeout Interval: The timeout period is not set.
    Log level: info

Summary:
There are 0 recommended code lines to modify.

For the details information on multi-thread races, please check:
    /home/DevKit_Software/dr-check_test_20250512070815_1256.json
    /home/DevKit_Software/dr-check_test_20250512070815_1256.html
    /home/DevKit_Software/dr-check_test_20250512070815_1256.csv