OpenMP-Examples/History.tex

\cchapter{Document Revision History}{history}
\label{chap:history}

%=====================================
\section{Changes from 5.2.2 to 6.0}
\label{sec:history_522_to_60}

\begin{itemize}
\item General changes:
\begin{itemize}
  \item Added a set of structured LaTeX environments for specifying
    language-dependent text.  This allows extracting language-specific
    content of the Examples document.  Refer to the content of
    \examplesblob{v6.0/Contributions.md} for details.
\end{itemize}

\item Added the following examples for the 6.0 features:
\begin{itemize}
  \item \kcode{omp::decl} attribute for declarative directives in C/C++
    (\specref{sec:attributes})
  \item \kcode{transparent} clause on the \kcode{task} construct to enable dependences
     between non-sibling tasks (\specref{subsec:depend_trans_task})
  \item Task dependences for \kcode{taskloop} construct
    (\specref{sec:taskloop_depend})
  \item \kcode{num_threads} clause that appears inside \kcode{target} region
    (\specref{subsec:target_teams_num_teams})
  \item \kcode{nowait} clause with argument on the \kcode{target} construct to control deferment 
     of target task (\specref{subsec:async_target_nowait_arg})
  \item Traits for specifying devices (\specref{sec:device_env_traits})
  \item \kcode{apply} clause with modifier argument to 
    support selective loop transformations
    (\specref{sec:apply_clause})
  \item Reduction on private variables in a \kcode{parallel} region
    (\specref{subsec:priv_reduction})
  \item \kcode{induction} clause (\specref{subsec:induction})
    and user-defined induction (\specref{subsec:user-defined-induction})
  \item \kcode{init_complete} clause for \kcode{scan} directive to 
    support initialization phase in scan operation
    (\specref{sec:scan})
  \item \kcode{assume} construct with \kcode{no_openmp} and \kcode{no_parallelism} clauses (\specref{sec:assumption})
  \item \kcode{num_threads} clause with a list
    (\specref{subsec:icv_nthreads})
  \item \kcode{dispatch} construct to control variant substitution
    for a procedure call (\specref{sec:dispatch})
\end{itemize}

\item Other changes:
\begin{itemize}
  \item Changed attribute specifier as a directive form from C++ only to C/C++
    (\specref{chap:directive_syntax})
  \item Added missing \bcode{include <omp.h>} in Example \example{atomic.4.c}
    and \bcode{use omp_lib} in Example \example{atomic.4.f90}
    (\specref{sec:atomic_hint})
  \item Fixed the function declaration order for variant functions in
    Examples \example{selector_scoring.[12].c} and Fortran pointer
    initialization in Example \example{selector_scoring.2.f90}
    (\specref{subsec:context_selector_scoring})
  \item Replaced the deprecated use of \plc{combiner-exp} 
    in \kcode{declare reduction} directive with \kcode{combiner} clause
    (\specref{subsec:UDR} and \specref{sec:Updated Examples})
  \item Fixed the initialization of Fortran pointers 
    in Example \example{cancellation.2.f90} and changed to
    use \kcode{atomic write} for performing atomic writes
    (\specref{sec:cancellation})
  \item Added missing \kcode{declare target} directive for external procedure
    called inside \kcode{target} region in Example 
    \example{requires.1.f90} (\specref{sec:requires})
\end{itemize}

\end{itemize}

%=====================================
\section{Changes from 5.2.1 to 5.2.2}
\label{sec:history_521_to_522}

\begin{itemize}
\item To improve the style of the document, a set of macros was introduced
  and consistently used for language keywords, names, concepts, and user codes
  in the text description of the document.  Refer to the content of 
  \examplesblob{v5.2.2/Contributions.md}
  for details.

\item Added the following examples:
\begin{itemize}
  \item Orphaned and nested \kcode{loop} constructs (\specref{sec:loop})
  \item \kcode{all} variable category for the \kcode{defaultmap} clause
    (\specref{sec:defaultmap})
  \item \kcode{target update} construct using a custom mapper
    (\specref{subsec:target_update_mapper})
  \item \kcode{indirect} clause for indirect procedure calls in a
    \kcode{target} region (\specref{subsec:indirect})
  \item \kcode{omp_target_memcpy_async} routine with depend object
    (\specref{subsec:target_mem_and_device_ptrs})
  \item Synchronization hint for atomic operation (\specref{sec:atomic_hint})
  \item Implication of passing shared variable to a procedure
    in Fortran (\specref{sec:fort_shared_var})
  \item Assumption directives for providing additional information
    about program properties (\specref{sec:assumption})
  \item Mapping behavior of scalars, pointers, references (C++) and associate names
        (Fortran) when unified shared memory is required
    (\specref{sec:requires})
  \item \kcode{begin declare variant} paired with \kcode{end declare variant}
    example to show use of nested declare variant 
    directives (\specref{subsec:declare_variant})
  \item Explicit scoring in context selectors
    (\specref{subsec:context_selector_scoring})
\end{itemize}

\item Miscellaneous changes:
\begin{itemize}
  \item Included a general statement in Introduction about the number of 
    threads used throughout the examples document (\specref{sec:examples})
  \item Clarified the mapping of virtual functions in \kcode{target} regions
    (\specref{sec:virtual_functions})
  \item Added missing \kcode{declare target} directive for procedures
    called inside \kcode{target} region in \example{Examples} 
    \example{declare_mapper.1.f90} (\specref{sec:declare_mapper}),
    \example{target_reduction.*.f90} (\specref{subsec:target_reduction}), 
    and \example{target_task_reduction.*.f90}
    (\specref{subsec:target_task_reduction})
  \item Added missing \kcode{end target} directive in 
    \example{Example declare_mapper.3.f90}
    (\specref{sec:declare_mapper})
  \item Removed example for \kcode{flush} without a list from Synchronization 
    since the example is confusing and the use of \kcode{flush} is already
    covered in other examples
    (\specref{chap:synchronization})
  \item \docref{declare variant Directive} and \docref{Metadirective} sections were moved to
         subsections in the new \docref{Context-based Variant Selection} section, 
         with a section introduction on context selectors.
    (\specref{sec:context_based_variants})
  \item Fixed a typo (`\kcode{for}' $\rightarrow$ `\kcode{do}') in 
    \example{Example metadirective.4.f90}
    (\specref{subsec:metadirective})
\end{itemize}

\end{itemize}

%=====================================
\section{Changes from 5.2 to 5.2.1}
\label{sec:history_52_to_521}

\begin{itemize}
\item General changes:
\begin{itemize}
\item Updated source metadata tags for all examples to use an improved form
 (see \examplesblob{v5.2.1/Contributions.md})
\item Explicitly included the version tag \verlabel[pre\_]{3.0} in those 
 examples that did not contain a version tag previously
\end{itemize}

\item Added the following examples for the 5.2 features:
\begin{itemize}
  \item \kcode{uses_allocators} clause for the use of allocators in 
  \kcode{target} regions (\specref{sec:allocators})
\end{itemize}
\item Added the following examples for the 5.1 features:
\begin{itemize}
  \item The \kcode{inoutset} dependence type (\specref{subsec:task_concurrent_depend})
  \item Atomic compare and capture (\specref{sec:cas})
\end{itemize}
\item Added the following examples for the 5.0 features:
\begin{itemize}
  \item \kcode{declare target} directive with \kcode{device_type(nohost)}
     clause (\specref{subsec:declare_target_device_type})
  \item \kcode{omp_pause_resource} and \kcode{omp_pause_resource_all}
     routines (\specref{sec:pause_resource})
\end{itemize}

\item Miscellaneous fixes:
\begin{itemize}
  \item Cast to implementation-defined enum type \kcode{omp_event_handle_t} 
    now uses \bcode{uintptr_t} (not \bcode{void *}) in
    \example{Example task_detach.2.c}
    (\specref{sec:task_detachment})
  \item Moved Fortran \kcode{requires} directive into program main (\ucode{rev_off}), 
    the program unit, in \example{Example target_reverse_offload.7.f90}
    (\specref{subsec:target_reverse_offload})
  \item Fixed an inconsistent use of mapper in \example{Example target_mapper.3.f90}
    (\specref{sec:declare_mapper})
  \item Added a missing semicolon at end of \ucode{XOR1} class definition in
    \example{Example declare_target.2a.cpp}
    (\specref{subsec:declare_target_class})
  \item Fixed the placement of \kcode{declare simd} directive in 
    \example{Examples linear_modifier.*.f90} (\specref{sec:linear_modifier})
    and added a general statement about where a Fortran declarative
    directive can appear (\specref{chap:directive_syntax})
  \item Fixed mismatched argument list in \example{Example fort_sa_private.5.f}
    (\specref{sec:fort_sa_private})
  \item Moved the placement of \kcode{declare target enter}
    directive after function declaration
    (\specref{subsec:target_task_reduction})
  \item Fixed an incorrect use of \kcode{omp_in_parallel} routine in 
    \example{Example metadirective.4}
    (\specref{subsec:metadirective})
  \item Fixed an incorrect value for \kcode{at} clause
    (\specref{subsec:error})
\end{itemize}

\end{itemize}

%=====================================
\section{Changes from 5.1 to 5.2}
\label{sec:history_51_to_52}

\begin{itemize}
\item General changes:
\begin{itemize}
\item Included a description of the semantics for OpenMP directive syntax
 (see \specref{chap:directive_syntax})
\item Reorganized the Introduction Chapter and moved the Feature 
Deprecation Chapter to Appendix~\ref{chap:deprecated_features}
\item Included a list of examples that were updated for feature deprecation
and replacement in each version (see Appendix~\ref{sec:Updated Examples})
\item Added Index entries
\end{itemize}

\item Updated the examples for feature deprecation and replacement in OpenMP 5.2.
See Table~\ref{tab:Deprecated Features} and 
Table~\ref{tab:Updated Examples 5.2} for details.

\item Added the following examples for the 5.2 features:
\begin{itemize}
  \item Mapping class objects with virtual functions
     (\specref{sec:virtual_functions})
  \item \kcode{allocators} construct for Fortran \bcode{allocate} statement
     (\specref{sec:allocators})
  \item Behavior of reallocation of variables through OpenMP allocator in
     Fortran (\specref{sec:allocators})
\end{itemize}

\item Added the following examples for the 5.1 features:
\begin{itemize}
  \item Clarification of optional \kcode{end} directive for strictly structured 
      block in Fortran (\specref{sec:fortran_free_format_comments})
  \item \kcode{filter} clause on \kcode{masked} construct (\specref{sec:masked})
  \item \kcode{omp_all_memory} reserved locator for specifying task dependences
      (\specref{subsec:depend_undefer_task})
  \item Behavior of Fortran allocatable variables in \kcode{target} regions
      (\specref{sec:fort_allocatable_array_mapping})
  \item Device memory routines in Fortran
      (\specref{subsec:target_mem_and_device_ptrs})
  \item Partial tiles from \kcode{tile} construct
      (\specref{sec:incomplete_tiles})
  \item Fortran associate names and selectors in \kcode{target} region
      (\specref{sec:associate_target})
  \item \kcode{allocate} directive for variable declarations and 
      \kcode{allocate} clause on \kcode{task} constructs
      (\specref{sec:allocators})
  \item Controlling concurrency and reproducibility with \kcode{order} clause
      (\specref{sec:reproducible_modifier})
\end{itemize}

\item Added other examples:
\begin{itemize}
  \item Using lambda expressions with \kcode{target} constructs
     (\specref{sec:lambda_expressions})
  \item Target memory and device pointer routines
     (\specref{subsec:target_mem_and_device_ptrs})
  \item Examples to illustrate the ordering properties of 
     the \plc{flush} operation (\specref{sec:mem_model})
  \item User selector in the \kcode{metadirective} directive
     (\specref{subsec:metadirective})
\end{itemize}

\end{itemize}

%=====================================
\section{Changes from 5.0.1 to 5.1}
\label{sec:history_501_to_51}

\begin{itemize}
\item General changes:
\begin{itemize}
  \item Replaced \kcode{master} construct example with equivalent \kcode{masked} construct example (\specref{sec:masked})
  \item Primary thread is now used to describe thread number 0 in the current team
  \item \kcode{primary} thread affinity policy is now used to specify that every 
      thread in the team is assigned to the same place as the primary thread (\specref{subsec:affinity_primary})
  \item The \kcode{omp_lock_hint_*} constants have been renamed \kcode{omp_sync_hint_*} (\specref{sec:critical}, \specref{sec:locks})
\end{itemize}

\item Added the following new chapters:
\begin{itemize}
  \item Deprecated Features (on page~\pageref{chap:deprecated_features})
  \item Directive Syntax (\specref{chap:directive_syntax})
  \item Loop Transformations (\specref{chap:loop_transformations})
  \item OMPT Interface (\specref{chap:ompt_interface})
\end{itemize}

\item Added the following examples for the 5.1 features:
\begin{itemize}
  \item OpenMP directives in C++ \plc{attribute} specifiers
    (\specref{sec:attributes})
  \item Directive syntax adjustment to allow Fortran \bcode{BLOCK} ... 
    \bcode{END BLOCK} as a structured block 
      (\specref{sec:fortran_free_format_comments})
  \item \kcode{omp_target_is_accessible} API routine
      (\specref{sec:pointer_mapping})
  \item Fortran allocatable array mapping in \kcode{target} regions (\specref{sec:fort_allocatable_array_mapping})
  \item \kcode{begin declare target} (with
        \kcode{end declare target}) directive
      (\specref{subsec:declare_target_class})
  \item \kcode{tile} construct             (\specref{sec:tile})
  \item \kcode{unroll} construct           (\specref{sec:unroll})
  \item Reduction with the \kcode{scope} construct
      (\specref{subsec:reduction_scope})
  \item  \kcode{metadirective} directive with dynamic \kcode{condition} selector
      (\specref{subsec:metadirective})
  \item \kcode{interop} construct  (\specref{sec:interop})
  \item Environment display with the \kcode{omp_display_env} routine
      (\specref{subsec:display_env})
  \item \kcode{error} directive  (\specref{subsec:error})
\end{itemize}

\item Included additional examples for the 5.0 features:
\begin{itemize}
  \item \kcode{collapse} clause for non-rectangular loop nest
      (\specref{sec:collapse})
  \item \kcode{detach} clause for tasks (\specref{sec:task_detachment})
  \item Pointer attachment for a structure member (\specref{sec:structure_mapping})
  \item Host and device pointer association with the \kcode{omp_target_associate_ptr} routine (\specref{sec:target_associate_ptr})
  
  \item Sample code on activating the tool interface 
      (\specref{sec:ompt_start})
\end{itemize}

\item Added other examples:
\begin{itemize}
  \item The \kcode{omp_get_wtime} routine (\specref{subsec:get_wtime})
\end{itemize}
\end{itemize}


%=====================================
\section{Changes from 5.0.0 to 5.0.1}
\label{sec:history_50_to_501}

\begin{itemize}
\item Added version tags \verlabel{\plc{x.y}} in example labels 
and the corresponding source codes for all examples that feature
OpenMP 3.0 and later. 

\item Included additional examples for the 5.0 features:

\begin{itemize}
\item Extension to the \kcode{defaultmap} clause
(\specref{sec:defaultmap})
\item Transferring noncontiguous data with the \kcode{target update} directive in Fortran (\specref{sec:array-shaping})
\item \kcode{conditional} modifier for the \kcode{lastprivate} clause                             (\specref{sec:lastprivate})
\item \kcode{task} modifier for the \kcode{reduction} clause                                      (\specref{subsec:task_reduction})
\item Reduction on combined target constructs                                                     (\specref{subsec:target_reduction})
\item Task reduction with \kcode{target} constructs 
   (\specref{subsec:target_task_reduction})
\item \kcode{scan} directive for returning the \emph{prefix sum} of a reduction                  (\specref{sec:scan})

\end{itemize}

\item Included additional examples for the 4.x features:

\begin{itemize}
\item Dependence for undeferred tasks
(\specref{subsec:depend_undefer_task})
\item \kcode{ref}, \kcode{val}, \kcode{uval} modifiers for \kcode{linear} clause (\specref{sec:linear_modifier})

\end{itemize}

\item Clarified the description of pointer mapping and pointer attachment in 
\specref{sec:pointer_mapping}.
\item Clarified the description of memory model examples
in \specref{sec:mem_model}.

\end{itemize}


\section{Changes from 4.5.0 to 5.0.0}
\label{sec:history_45_to_50}

\begin{itemize}
\item Added the following examples for the 5.0 features:

\begin{itemize}
\item Extended \kcode{teams} construct for host execution     (\specref{sec:host_teams})
\item \kcode{loop} and \kcode{teams loop} constructs specify loop iterations that can execute concurrently 
                                                             (\specref{sec:loop})
\item Task data affinity is indicated by \kcode{affinity} clause of \kcode{task} construct
                                                             (\specref{sec: task_affinity})
\item Display thread affinity with \kcode{OMP_DISPLAY_AFFINITY} environment variable or \kcode{omp_display_affinity()} API routine
                                                             (\specref{sec:affinity_display})
\item \kcode{taskwait} with dependences                       (\specref{subsec:taskwait_depend})
\item \kcode{mutexinoutset} task dependences                  (\specref{subsec:task_dep_mutexinoutset})
\item Multidependence Iterators (in \kcode{depend} clauses)   (\specref{subsec:depend_iterator})
\item Combined constructs: \kcode{parallel master taskloop} and \kcode{parallel master taskloop simd}
                                                                                  (\specref{sec:parallel_masked_taskloop})
\item Reverse Offload through \kcode{ancestor} modifier of \kcode{device} clause.    (\specref{subsec:target_reverse_offload})
\item Pointer Mapping  - behavior of mapped pointers                              (\specref{sec:pointer_mapping})   %Example_target_ptr_map*
\item Structure Mapping  - behavior of mapped structures                          (\specref{sec:structure_mapping}) %Examples_target_structure_mapping.tex target_struct_map*
\item Array Shaping with the \plc{shape-operator}                                 (\specref{sec:array-shaping})
\item The \kcode{declare mapper} directive                                  (\specref{sec:declare_mapper})
\item Acquire and Release Semantics Synchronization: Memory ordering 
      clauses \kcode{acquire}, \kcode{release}, and \kcode{acq_rel} were added
      to flush and atomic constructs
                                                                                  (\specref{sec:acquire_and_release_semantics})
\item \kcode{depobj} construct provides dependence objects for subsequent use in \kcode{depend} clauses
                                                                                  (\specref{sec:depobj})
\item \kcode{reduction} clause for \kcode{task} construct                           (\specref{subsec:task_reduction})
\item \kcode{reduction} clause for \kcode{taskloop} construct                       (\specref{subsec:taskloop_reduction})
\item \kcode{reduction} clause for \kcode{taskloop simd} construct           (\specref{subsec:taskloop_reduction})
\item Memory Allocators for making OpenMP memory requests with traits             (\specref{sec:allocators})
\item \kcode{requires} directive specifies required features of implementation     (\specref{sec:requires})
\item \kcode{declare variant} directive - for function variants
(\specref{subsec:declare_variant})
\item \kcode{metadirective} directive  - for directive variants
(\specref{subsec:metadirective})
\item \kcode{OMP_TARGET_OFFLOAD} Environment Variable  - controls offload behavior (\specref{sec:target_offload})
\end{itemize}

\item Included the following additional examples for the 4.x features:
\begin{itemize}
\item more taskloop examples (\specref{sec:taskloop})
\item user-defined reduction (UDR) (\specref{subsec:UDR})
%NEW 5.0
%\item \code{target} \code{enter} and \code{exit} \code{data} unstructured data constructs  (\specref{sec:target_enter_exit_data}) %Example_target_unstructured_data.* ?

\end{itemize}
\end{itemize}

\section{Changes from 4.0.2 to 4.5.0}
\begin{itemize}
\item Reorganized into chapters of major topics
\item Included file extensions in example labels to indicate source type
\item Applied the explicit \kcode{map(tofrom)} for scalar variables 
      in a number of examples to comply with 
      the change of the default behavior for scalar variables from 
      \kcode{map(tofrom)} to \kcode{firstprivate} in the 4.5 specification
\item Added the following new examples:

\begin{itemize}
\item \kcode{linear} clause in loop constructs     (\specref{sec:linear_in_loop})
\item \kcode{priority} clause for \kcode{task} construct (\specref{sec:task_priority})
\item \kcode{taskloop} construct                   (\specref{sec:taskloop})
\item \plc{directive-name} modifier in multiple \kcode{if} clauses on
a combined construct                              (\specref{subsec:target_if})
\item unstructured data mapping                   (\specref{sec:target_enter_exit_data})
\item \kcode{link} clause for \kcode{declare target} directive 
                                                  (\specref{subsec:declare_target_link})
\item asynchronous target execution with \kcode{nowait} clause (\specref{sec:async_target_exec_depend})
\item device memory routines and device pointers  (\specref{subsec:target_mem_and_device_ptrs})
\item doacross loop nest                          (\specref{sec:doacross})
\item locks with hints                            (\specref{sec:locks})
\item C/C++ array reduction                       (\specref{subsec:reduction})
\item C++ reference types in data sharing clauses (\specref{sec:cpp_reference})
\end{itemize}

\end{itemize}

\section{Changes from 4.0.1 to 4.0.2}

\begin{itemize}
\item Names of examples were changed from numbers to mnemonics
\item Added SIMD examples                         (\specref{sec:SIMD})
\item Applied miscellaneous fixes in several source codes
\item Added the revision history
\end{itemize}

\section{Changes from 4.0 to 4.0.1}

Added the following new examples:
\begin{itemize}
\item the \kcode{proc_bind} clause   (\specref{sec:affinity})
\item the \kcode{taskgroup} construct (\specref{sec:taskgroup})
\end{itemize}

\section{Changes from 3.1 to 4.0}

\begin{itemize}
\item Beginning with OpenMP 4.0, examples were placed in a separate document
      from the specification document.
\item Version 4.0 added the following new examples:

\begin{itemize}
\item task dependences                       (\specref{sec:task_depend})
\item \kcode{target} construct                (\specref{sec:target})
\item array sections in device constructs    (\specref{sec:array_sections})
\item \kcode{target data} construct    (\specref{sec:target_data})
\item \kcode{target update} construct  (\specref{sec:target_update})
\item \kcode{declare target} directive (\specref{sec:declare_target})
\item \kcode{teams} constructs                (\specref{sec:teams})
\item asynchronous execution of a \kcode{target} region using tasks (\specref{subsec:async_target_with_tasks})
\item device runtime routines                (\specref{sec:device})
\item Fortran ASSOCIATE construct            (\specref{sec:associate})
\item cancellation constructs                (\specref{sec:cancellation})
\end{itemize}

\end{itemize}