From patchwork Thu Sep 7 08:56:04 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 75424 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 697063857C41 for ; Thu, 7 Sep 2023 08:56:28 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa3.mentor.iphmx.com (esa3.mentor.iphmx.com [68.232.137.180]) by sourceware.org (Postfix) with ESMTPS id 86CA73858430 for ; Thu, 7 Sep 2023 08:56:09 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 86CA73858430 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com X-CSE-ConnectionGUID: xqS02tbbTgawpsNJSi/GLQ== X-CSE-MsgGUID: +526FmJfREmD/pqZ0RtC4A== X-IronPort-AV: E=Sophos;i="6.02,234,1688457600"; d="diff'?scan'208";a="16329105" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa3.mentor.iphmx.com with ESMTP; 07 Sep 2023 00:56:08 -0800 IronPort-SDR: X1roQiPo7Jq8Rj5t4M7T8su+GIObNrPXBGjWOJPCKGcJJhwUrCbTdPWJes+eqLH08zELQeOlL2 AtQjB093VqhYPHBcXmawe4V8tGrZ2M1fzyRUl7mnnUauIWtVK+GDQb7Xe3uOH5oAd01P8RpngG jvKMIKtAsIv+DXaGYrRnV+VevRU0Yfqwm9jj9l2rjYusBnEjU4f1Hmnjah/z8gS49uwfSIpMXT zn9ODAE2VHiLI1y/T25wKVnAHzvhyBp2GLn9hI+Qj2jOSXTa5QGwipgZ0PUDKAlpjeDTyGM05z kWQ= Message-ID: Date: Thu, 7 Sep 2023 10:56:04 +0200 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.15.0 Content-Language: en-US To: gcc-patches , Jakub Jelinek , Sandra Loosemore From: Tobias Burnus Subject: [Patch] libgomp.texi: Fix ICV var name, document some memory management routines X-Originating-IP: [137.202.0.90] X-ClientProxiedBy: svr-ies-mbx-15.mgc.mentorg.com (139.181.222.15) To svr-ies-mbx-12.mgc.mentorg.com (139.181.222.12) X-Spam-Status: No, score=-11.3 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" Main reason was to fix an ICV value; as collateral change, I also added documentation for some of the memory-management functions. Comments, suggestions? If not, I will commit it soon. Tobias ----------------- Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634 München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht München, HRB 106955 libgomp.texi: Fix ICV var name, document some memory management routines libgomp/ * libgomp.texi (Memory Management Routines): New; add documentation for omp_init_allocator, omp_destroy_allocator, omp_set_default_allocator, omp_get_default_allocator. (OMP_ALLOCATOR): Fix ICV var name; add see-also references. libgomp/libgomp.texi | 160 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 145 insertions(+), 15 deletions(-) diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index 4aad8cc52f4..c6cd825bbaa 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -518,7 +518,7 @@ specification in version 5.2. * Timing Routines:: * Event Routine:: @c * Interoperability Routines:: -@c * Memory Management Routines:: +* Memory Management Routines:: @c * Tool Control Routine:: @c * Environment Display Routine:: @end menu @@ -2112,17 +2112,17 @@ event handle that has already been fulfilled is also undefined. @c * omp_get_interop_rc_desc:: @c @end menu -@c @node Memory Management Routines -@c @section Memory Management Routines -@c -@c Routines to manage and allocate memory on the current device. -@c They have C linkage and do not throw exceptions. -@c -@c @menu -@c * omp_init_allocator:: -@c * omp_destroy_allocator:: -@c * omp_set_default_allocator:: -@c * omp_get_default_allocator:: +@node Memory Management Routines +@section Memory Management Routines + +Routines to manage and allocate memory on the current device. +They have C linkage and do not throw exceptions. + +@menu +* omp_init_allocator:: Create an allocator +* omp_destroy_allocator:: Destroy an allocator +* omp_set_default_allocator:: Set the default allocator +* omp_get_default_allocator:: Get the default allocator @c * omp_alloc:: @c * omp_aligned_alloc:: @c * omp_free:: @@ -2131,7 +2131,136 @@ event handle that has already been fulfilled is also undefined. @c * omp_realloc:: @c * omp_get_memspace_num_resources:: /TR11 @c * omp_get_submemspace:: /TR11 -@c @end menu +@end menu + + + +@node omp_init_allocator +@subsection @code{omp_init_allocator} -- Create an allocator +@table @asis +@item @emph{Description}: +Create an allocator that uses the specified memory space and has the specified +traits; if an allocator that fulfills the requirements cannot be created, +@code{omp_null_allocator} is returned. + +The predefined memory spaces and available traits can be found at +@ref{OMP_ALLOCATOR}, where the trait names have to be be prefixed by +@code{omp_atk_} (e.g. @code{omp_atk_pinned}) and the named trait values by +@code{omp_atv_} (e.g. @code{omp_atv_true}); additionally, @code{omp_atv_default} +may be used as trait value to specify that the default value should be used. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{omp_allocator_handle_t omp_init_allocator(} +@item @tab @code{ omp_memspace_handle_t memspace,} +@item @tab @code{ int ntraits,} +@item @tab @code{ const omp_alloctrait_t traits[]);} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{function omp_init_allocator(memspace, ntraits, traits)} +@item @tab @code{integer (kind=omp_allocator_handle_kind) :: omp_init_allocator} +@item @tab @code{integer (kind=omp_memspace_handle_kind), intent(in) :: memspace} +@item @tab @code{integer, intent(in) :: ntraits} +@item @tab @code{type (omp_alloctrait), intent(in) :: traits(*)} +@end multitable + +@item @emph{See also}: +@ref{OMP_ALLOCATOR}, @ref{Memory allocation}, @ref{omp_destroy_allocator} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.7.2 +@end table + + + +@node omp_destroy_allocator +@subsection @code{omp_destroy_allocator} -- Destroy an allocator +@table @asis +@item @emph{Description}: +Releases all resources used by a memory allocator, which must not represent +a predefined memory allocator. Accessing memory after its allocator has been +destroyed has unspecified behavior. Passing @code{omp_null_allocator} to the +routine is permitted but will have no effect. + + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void omp_destroy_allocator (omp_allocator_handle_t allocator);} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{subroutine omp_destroy_allocator(allocator)} +@item @tab @code{integer (kind=omp_allocator_handle_kind), intent(in) :: allocator} +@end multitable + +@item @emph{See also}: +@ref{omp_init_allocator} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.7.3 +@end table + + + +@node omp_set_default_allocator +@subsection @code{omp_set_default_allocator} -- Set the default allocator +@table @asis +@item @emph{Description}: +Sets the default allocator that is used when no allocator has been specified +in the @code{allocate} or @code{allocator} clause or if an OpenMP memory +routine is invoked with the @code{omp_null_allocator} allocator. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void omp_set_default_allocator(omp_allocator_handle_t allocator);} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{subroutine omp_set_default_allocator(allocator)} +@item @tab @code{integer (kind=omp_allocator_handle_kind), intent(in) :: allocator} +@end multitable + +@item @emph{See also}: +@ref{omp_get_default_allocator}, @ref{omp_init_allocator}, @ref{OMP_ALLOCATOR}, +@ref{Memory allocation} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.7.4 +@end table + + + +@node omp_get_default_allocator +@subsection @code{omp_get_default_allocator} -- Get the default allocator +@table @asis +@item @emph{Description}: +The routine returns the default allocator that is used when no allocator has +been specified in the @code{allocate} or @code{allocator} clause or if an +OpenMP memory routine is invoked with the @code{omp_null_allocator} allocator. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{omp_allocator_handle_t omp_get_default_allocator();} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{function omp_get_default_allocator()} +@item @tab @code{integer (kind=omp_allocator_handle_kind) :: omp_get_default_allocator} +@end multitable + +@item @emph{See also}: +@ref{omp_set_default_allocator}, @ref{OMP_ALLOCATOR} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.7.5 +@end table + + @c @node Tool Control Routine @c @@ -2204,7 +2333,7 @@ variable is not set. @section @env{OMP_ALLOCATOR} -- Set the default allocator @cindex Environment Variable @table @asis -@item @emph{ICV:} @var{available-devices-var} +@item @emph{ICV:} @var{def-allocator-var} @item @emph{Scope:} data environment @item @emph{Description}: Sets the default allocator that is used when no allocator has been specified @@ -2276,7 +2405,8 @@ OMP_ALLOCATOR=omp_low_lat_mem_space:pinned=true,partition=nearest @end smallexample @item @emph{See also}: -@ref{Memory allocation} +@ref{Memory allocation}, @ref{omp_get_default_allocator}, +@ref{omp_set_default_allocator} @item @emph{Reference}: @uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.21