1783023 - Consider specializing C++ clang thread-safety annotations GUARDED_BY and REQUIRES relationships to show them as a related edge in search results and an explicit context menu search

Status: NEW

(Webtools :: Searchfox, enhancement)

Description

[Andrew Sutherland [:asuth] (he/him)]

Thanks to :jesup's amazing work on bug 1207753 (and a cast of many reviewers!) fields can now be annotated with GUARDED_BY(mSomeMutex) and methods can be annotated with REQUIRES(mMutex) and we should consider specializing this.

Searchfox already understands the uses in GUARDED_BY and REQUIRES as uses, which works out quite well, but it would be interesting to be able to semantically recognize this relationship, perhaps as a specific type of "usage" as experimentally done in this comment here, but probably more importantly to be able to filter searches based on whether fields/methods are guarded by a mutex or not and to be able to visually indicate guarded versus unguarded in source code listings and in diagrams.

An orthogonal but interesting additional analysis would be if all C++ uses could also be labeled as covered by a mutex or not. It should be the case that all uses of a GUARDED_BY field should be covered by a mutex, but for non-guarded fields, it could potentially be interesting to be able to know that the field is sometimes accessed with a mutex and sometimes not and have this information both expressed on the symbol via its own visual indicator, as well as providing a way to filter/facet search results to ad-hoc-guarded and unguarded uses. This presumably ends up depending on the semantic linkage mechanism proposed in bug 1727789 if we want to address this more generically. It also seems reasonable to specialize on.

Potential search-related specialization:

• Search queries:
  • A filter could limit matches to guarded/ad-hoc-guarded/unguarded fields/methods.
• Search results:
  • Guarded fields could explicitly display a relationship edge/upsell to their guard.
  • Mutexes could explicitly have edges/upsells to their guarded fields/methods rather than going through the use source line.
• Context menu:
  • Assuming the search filtering is useful, we could also add an explicit context-menu option to search for what the mutex explicitly guards for the mutex symbol itself.
  • For guarded methods/fields, we could add an explicit goto or search for the guard. (Search might be most pragmatic if we can make sure to start folding in any block comments on the guard.)

Source code listings / diagrams:

• Guarded fields/methods could have a special coloring or badge.