<commit_before>\chapter{\TRACE API}\label{cha:API}

There are two levels of the API in the \TRACE instrumentation package. Basic API refers to the basic functionality provided and includes emitting events, source code tracking, changing instrumentation mode and so. Extended API is an {\em experimental} addition to provide several of the basic API within single and powerful calls using specific data structures.

\section{Basic API}\label{sec:BasicAPI}

The following routines are defined in the {\tt \$\{EXTRAE\_HOME\}/include/extrae\_user\_events.h}. These routines are intended to be called by C/C++ programs. The instrumentation package also provides bindings for Fortran applications. The Fortran API bindings have the same name as the C API but honoring the Fortran compiler function name mangling scheme. The \TRACE constants for Fortran applications can be included from {\tt \$\{EXTRAE\_HOME\}/include/extraef\_user\_events.h}.

\begin{itemize}

 \item {\tt void Extrae\_init (void)}\\
 Initializes the tracing library.\\
 {\bf NOTE:} This routine is called automatically by either {\tt MPI\_Init} or when tracing is performed by the DynInst launcher.

 \item {\tt void Extrae\_fini (void)}\\
 Finalizes the tracing library and dumps the intermediate tracing buffers onto disk.\\
 {\bf NOTE:} This routine is called automatically by either {\tt MPI\_Finalize} or when the tracing is performed by the DynInst launcher.

 \item {\tt void Extrae\_event (unsigned event, unsigned value)}\\
 The Extrae\_event adds a single timestamped event into the tracefile. The event has two arguments: type and value.

 Some common use of events are:<commit_msg>Add reference to a new API call<commit_after>\chapter{\TRACE API}\label{cha:API}

There are two levels of the API in the \TRACE instrumentation package. Basic API refers to the basic functionality provided and includes emitting events, source code tracking, changing instrumentation mode and so. Extended API is an {\em experimental} addition to provide several of the basic API within single and powerful calls using specific data structures.

\section{Basic API}\label{sec:BasicAPI}

The following routines are defined in the {\tt \$\{EXTRAE\_HOME\}/include/extrae\_user\_events.h}. These routines are intended to be called by C/C++ programs. The instrumentation package also provides bindings for Fortran applications. The Fortran API bindings have the same name as the C API but honoring the Fortran compiler function name mangling scheme. The \TRACE constants for Fortran applications can be included from {\tt \$\{EXTRAE\_HOME\}/include/extraef\_user\_events.h}.

\begin{itemize}

 \item {\tt void Extrae\_init (void)}\\
 Initializes the tracing library.\\
 {\bf NOTE:} This routine is called automatically by either {\tt MPI\_Init} or when tracing is performed by the DynInst launcher.

 \item {\tt extrae\_init\_type\_t Extrae\_is\_initialized (void);}\\
 This routine tells whether the instrumentation has been initialized, and if so, also which mechanism was the first to initialize it (regular API, MPI or PACX initialization).

 \item {\tt void Extrae\_fini (void)}\\
 Finalizes the tracing library and dumps the intermediate tracing buffers onto disk.\\
 {\bf NOTE:} This routine is called automatically by either {\tt MPI\_Finalize} or when the tracing is performed by the DynInst launcher.

 \item {\tt void Extrae\_event (unsigned event, unsigned value)}\\
 The Extrae\_event adds a single timestamped event into the tracefile. The event has two arguments: type and value.

 Some common use of events are:
{'fraction_non_alphanumeric': 0.07602012297372834, 'fraction_numerical': 0.0, 'mean_word_length': 4.390060240963855, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2441744', 'n_tokens_mistral': 892, 'n_tokens_neox': 856, 'n_words': 477}