mirrors/git
0
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-12-02 22:43:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

api-trace2.txt: elminate section describing the public trace2 API

Browse Source 
Eliminate the mostly obsolete `Public API` sub-section from the
`Trace2 API` section in the documentation.  Strengthen the referral
to `trace2.h`.

Most of the technical information in this sub-section was moved to
`trace2.h` in 6c51cb525d (trace2: move doc to trace2.h, 2019-11-17) to
be adjacent to the function prototypes.  The remaining text wasn't
that useful by itself.

Furthermore, the text would need a bit of overhaul to add routines
that do not immediately generate a message, such as stopwatch timers.
So it seemed simpler to just get rid of it.

Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jeff Hostetler 2022-10-24 13:41:02 +00:00 committed by Junio C Hamano
parent 5bbb925137
commit 8e8c5ad27a
1 changed files with 7 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
Documentation/technical/api-trace2.txt
View File

@ -148,20 +148,18 @@ filename collisions).
== Trace2 API
All public Trace2 functions and macros are defined in `trace2.h` and
`trace2.c`. All public symbols are prefixed with `trace2_`.
The Trace2 public API is defined and documented in `trace2.h`; refer to it for
more information. All public functions and macros are prefixed
with `trace2_` and are implemented in `trace2.c`.
There are no public Trace2 data structures.
The Trace2 code also defines a set of private functions and data types
in the `trace2/` directory. These symbols are prefixed with `tr2_`
and should only be used by functions in `trace2.c`.
and should only be used by functions in `trace2.c` (or other private
source files in `trace2/`).
== Conventions for Public Functions and Macros
The functions defined by the Trace2 API are declared and documented
in `trace2.h`. It defines the API functions and wrapper macros for
Trace2.
=== Conventions for Public Functions and Macros
Some functions have a `_fl()` suffix to indicate that they take `file`
and `line-number` arguments.
@ -172,52 +170,7 @@ take a `va_list` argument.
Some functions have a `_printf_fl()` suffix to indicate that they also
take a `printf()` style format with a variable number of arguments.
There are CPP wrapper macros and `#ifdef`s to hide most of these details.
See `trace2.h` for more details. The following discussion will only
describe the simplified forms.
== Public API
All Trace2 API functions send a message to all of the active
Trace2 Targets. This section describes the set of available
messages.
It helps to divide these functions into groups for discussion
purposes.
=== Basic Command Messages
These are concerned with the lifetime of the overall git process.
e.g: `void trace2_initialize_clock()`, `void trace2_initialize()`,
`int trace2_is_enabled()`, `void trace2_cmd_start(int argc, const char **argv)`.
=== Command Detail Messages
These are concerned with describing the specific Git command
after the command line, config, and environment are inspected.
e.g: `void trace2_cmd_name(const char *name)`,
`void trace2_cmd_mode(const char *mode)`.
=== Child Process Messages
These are concerned with the various spawned child processes,
including shell scripts, git commands, editors, pagers, and hooks.
e.g: `void trace2_child_start(struct child_process *cmd)`.
=== Git Thread Messages
These messages are concerned with Git thread usage.
e.g: `void trace2_thread_start(const char *thread_name)`.
=== Region and Data Messages
These are concerned with recording performance data
over regions or spans of code. e.g:
`void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`.
Refer to trace2.h for details about all trace2 functions.
CPP wrapper macros are defined to hide most of these details.
== Trace2 Target Formats