{"id":4333,"date":"2020-12-13T14:43:39","date_gmt":"2020-12-13T20:43:39","guid":{"rendered":"https:\/\/coderrect.com\/?post_type=docs&p=4333"},"modified":"2021-01-06T15:02:39","modified_gmt":"2021-01-06T21:02:39","slug":"special-configurations","status":"publish","type":"docs","link":"https:\/\/coderrect.com\/docs\/special-configurations\/","title":{"rendered":"Special Configurations"},"content":{"rendered":"\n

Special Configurations<\/strong><\/h1>\n\n\n\n

<\/p>\n\n\n\n

Exclude Uninteresting Code Paths<\/h2>\n\n\n\n

This tutorial assumes that you have gone through one of the three starter case tutorials<\/a> and have successfully run Coderrect.<\/p>\n\n\n\n

By default, Coderrect traverses every function that is reachable from the\u00a0main<\/strong><\/em>\u00a0function (or from any of the\u00a0user-specified entry functions<\/a>). However, in many cases, users might regard certain functions as uninteresting in their own projects and therefore do not want Coderrect to analyze those functions. This can be done by setting configuration for \u201cskipFunctions<\/em><\/strong>\u201d in .coderrect.json:<\/p>\n\n\n\n

\/\/.coderrect.json\n\"skipFunctions\":[\n        \"print_msg\"\n] <\/pre>\n\n\n\n
In the above example, the function \u201cprint_msg<\/em><\/strong>\u201d will not be analyzed by Coderrect.<\/p>\n\n\n\n
\n\n\n\n
Analyzing Interesting Indirect Calls<\/h2>\n\n\n\n
This tutorial assumes that you have gone through one of the three starter case tutorials<\/a> and have successfully run Coderrect.<\/p>\n\n\n\n
To make Coderrect fast, in the default setting Coderrect only analyzes a limited number of indirect function calls (functions that are invoked through function pointers) for each call site. It is because that the number of targets that can be pointed by the function pointer can be large and analyzing each of them is time-consuming. This works well for common cases in practice. However, in cases where a call site has many targets, users can configure \u201cindirectFunctions<\/strong><\/em>\u201d to analyze all possible targets called in a function. For example:<\/p>\n\n\n\n
\"indirectFunctions\":[\n        \"OpBase_Consume\"\n] <\/pre>\n\n\n\n
In the above,\u00a0OpBase_Consume<\/em><\/strong>\u00a0is a function from\u00a0RedisGraph<\/a>\u00a0and it contains an indirect call\u00a0op->consume(op)<\/em><\/strong>\u00a0with a large number of possible call targets:<\/p>\n\n\n\n
inline Record OpBase_Consume(OpBase *op) {\n        return op->consume(op);\n}<\/pre>\n\n\n\n
The configuration instructs Coderrect to analyze all possible indirect call targets in the function \u201cOpBase_Consume<\/em><\/strong>\u201c.<\/p>\n\n\n\n
\n\n\n\n
Define Custom Lock APIs<\/h2>\n\n\n\n
Quick Start<\/h3>\n\n\n\n
To make Coderrect understand your custom lock APIs, please open your configuration file (the default one is $installDir\/conf\/coderrect.json), and add the following lines:<\/p>\n\n\n\n
{\n        ... ...\n        lockUnlockFunctions: {\n            \"MyMutexLockFunc\": \"MyMutexUnlockFunc\",\n            \"MySpinLockFunc\": \"MySpinUnlockFunc\"\n        }\n}<\/pre>\n\n\n\n
Introduction<\/h3>\n\n\n\n
Lock APIs (e.g. pthread_mutex) are the most common synchronization mechanism used by developers. Coderrect has the built-in support for std::lock, std::mutex, pthread_mutex, and pthread_spin_lock. However, developers may use third-party libraries that have their own lock APIs. Furthermore, developers may create their own lock APIs to fit the special needs. <\/p>\n\n\n\n
Coderrect relies on the configuration \u201clockUnlockFunctions\u201d to recognize these proprietary APIs.<\/p>\n\n\n\n
lockUnlockFunctions<\/h3>\n\n\n\n
The code below creates a naive custom spin lock and protects simultaneous access to the global variable \u201cx<\/em><\/strong>\u201d by using it.\u00a0<\/p>\n\n\n\n
#include <iostream>\n#include <atomic>\n#include <thread>\n\nstruct my_spinlock_t {\n    std::atomic<bool> a;\n\n    my_spinlock_t() : a(false) {}\n};\n\nvoid MySpinLock(my_spinlock_t* lock) {\n    bool expected = false;\n    while (!lock->a.compare_exchange_strong(expected, true))\n    ;\n}\n\nvoid MySpinUnlock(my_spinlock_t* lock) {\n    lock->a = false;\n}\n\nmy_spinlock_t lock;\nint x;\n\n\nvoid thread_function() {\n    MySpinLock(&lock);\n    x++;\n    std::cout << x << \"n\";\n    MySpinUnlock(&lock);\n}\n\n\nint main ()\n{\n    std::thread first (thread_function);\n    std::thread second (thread_function);\n    first.join();\n    second.join();\n    return 0;\n}<\/pre>\n\n\n\n
Let\u2019s run Coderrect with the default configuration:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Coderrect detects a race because it doesn\u2019t understand the meaning of MySpinLock and MySpinUnlcok and determines \u201cx<\/em><\/strong>\u201d are accessed by two threads simultaneously without synchronization.<\/p>\n\n\n\n
Now, let\u2019s tell Coderrect the meaning of MySpinLock\/MySpinUnlock with a custom local configuration file lockunlockfunc.json:<\/p>\n\n\n\n
{\n    \"lockUnlockFunctions\": {\n         \"MySpinLock\": \"MySpinUnlock\"\n    }\n}<\/pre>\n\n\n\n
The lockUnlockFunctions is a list of key-value pairs. Each pair has the name of the lock function as the key and the name of the unlock function as the value.<\/p>\n\n\n\n
Let\u2019s apply this configuration file to Coderrect and try again<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
You tell Coderrect to load and overlap the configuration file \u201clockunlockfunc.json\u201d to the default coderrect.json using \u201c-conf\u201d option. Now, Coderrect knows MySpinLock and MySpinUnlock are a pair of lock-unlock functions and makes correct reasoning of the thread interleave.<\/p>\n\n\n\n
Support Version<\/h3>\n\n\n\n
Coderrect 0.7.0+<\/p>\n\n\n\n
\n\n\n\n
Common Configurations<\/strong><\/h2>\n\n\n
\n\t\n\t\n\t\n\t
\n\t\t
HOW TO CUSTOMIZE CODERRECT DETECTION<\/h2>
Coderrect Scanner provides a suite of configurations to help you focus on the most important issues.<\/p><\/header>\n\t\t
\n  
\n\n    
\n      
\n  
\n    \n      How to make Coderrect Scanner exclude certain functions\u00a0in my code?\n    <\/a>\n  <\/h5>\n\n  
\n    
Config Coderrect to skip specified functions during race analysis.
\"skipFunctions\":[\u00a0<\/code>
\"FunctionName*\",\u00a0<\/code>
\"FunctionOther\"\u00a0<\/code>
]<\/code>

By default, Coderrect traverses every function that is reachable from the\u00a0main<\/code>\u00a0function (or from any of the\u00a0user-specified entry functions<\/a>). In many cases, users might regard certain functions as uninteresting and therefore do not want Coderrect to analyze them.<\/div>\n  <\/div>\n<\/div>
\n  
\n    \n      How to make Coderrect Scanner\u00a0exclude certain variables in my code?\n    <\/a>\n  <\/h5>\n\n  
\n    

Config Coderrect to skip analysis on specified variables.
\"ignoreRaceVariables\":[<\/code>
\"VariableName*\",<\/code>
\"VariableOtherName\"\u00a0<\/code>
]<\/code>

Check out a tutorial uses this configuration\u00a0here<\/a><\/strong><\/div>\n  <\/div>\n<\/div>
\n  
\n    \n      How to make Coderrect Scanner recognize custom lock\/unlock APIs?\n    <\/a>\n  <\/h5>\n\n  
\n    
Specify a list of custom lock\/unlock APIs so that Coderrect can make correct reasoning.
\"lockUnlockFunctions\": {<\/code>
\"MySpinLock\": \"MySpinUnlock\",<\/code>
\"MyMutexLock\": \"MyMutexUnlock\"\u00a0<\/code>
}<\/code>
Check out a tutorial uses this configuration\u00a0here<\/a><\/div>\n  <\/div>\n<\/div>\n    <\/div>\n  <\/div>\n\n<\/div>\n\t<\/div>\n<\/section>\n\n
\n\t\n\t\n\t\n\t
\n\t\t
HOW TO ANALYZE A LIBRARY<\/h2>
Coderrect Scanner can analyze a library without a main function<\/p><\/header>\n\t\t
\n  
\n\n    
\n      
\n  
\n    \n      I have a library without a main function, how to analyze it?\n    <\/a>\n  <\/h5>\n\n  
\n    
Specify entry points for libraries in the configuration file:
\"openlib\": {<\/code>
\"entryPoints\":[<\/code>
\"FunctionName*\",<\/code>
\"FunctionNameOther\"\u00a0<\/code>
]\u00a0<\/code>
}<\/code>
Check out a tutorial uses this configuration\u00a0here<\/a><\/strong><\/div>\n  <\/div>\n<\/div>\n    <\/div>\n  <\/div>\n\n<\/div>\n\t<\/div>\n<\/section>\n\n\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
Special Configurations Exclude Uninteresting Code Paths This tutorial assumes that you have gone through one of the three starter case tutorials and have successfully run Coderrect. By default, Coderrect traverses every function that is reachable<\/p>\n","protected":false},"author":182999572,"featured_media":0,"parent":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_coblocks_attr":"","_coblocks_dimensions":"","_coblocks_responsive_height":"","_coblocks_accordion_ie_support":"","advanced_seo_description":"","jetpack_seo_html_title":"","jetpack_seo_noindex":false,"jetpack_post_was_ever_published":false},"doc_category":[1414],"doc_tag":[],"jetpack_likes_enabled":false,"jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/docs\/4333"}],"collection":[{"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/users\/182999572"}],"replies":[{"embeddable":true,"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/comments?post=4333"}],"version-history":[{"count":13,"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/docs\/4333\/revisions"}],"predecessor-version":[{"id":4504,"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/docs\/4333\/revisions\/4504"}],"wp:attachment":[{"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/media?parent=4333"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/doc_category?post=4333"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/coderrect.com\/wp-json\/wp\/v2\/doc_tag?post=4333"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}