From patchwork Thu Oct 12 10:53:19 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 151922 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:612c:2908:b0:403:3b70:6f57 with SMTP id ib8csp1136349vqb; Thu, 12 Oct 2023 03:54:05 -0700 (PDT) X-Google-Smtp-Source: AGHT+IFZ2MuEJDPfOjlQA4Eiy3TIyZPSjXbCaouG5qlOer9s7V3xY8kZGlAwLqV+oD2z1h6qhTNX X-Received: by 2002:a17:906:10a:b0:9a1:cbe4:d029 with SMTP id 10-20020a170906010a00b009a1cbe4d029mr24775807eje.74.1697108045075; Thu, 12 Oct 2023 03:54:05 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1697108044; cv=none; d=google.com; s=arc-20160816; b=BecmlfVGKxn/L36UDmpzrPKBTLwZQiK4uEQ6gEp/53xt4HtuMYEkHVh+KFyJhFDLAP 5ekLAjU0MQzG7nGmjJo8K2L21oy2Vk+QZWX7nPc0lC0+OzedGIESwPHh0p0ms1syj9A/ onov6jGCKyDk1HkjxrRrKJJWyrRBu4JjCcXttnt/w1AB7/ATF6P+i6kfXH9SBOIbYLJS SRil4504YG//vtCxApUp+waTTj1Pu54WNpsGbVsqnthDoCIj1rkXbPYRW5qHlwzUiHQb wQgtTSAE7o58leMyh0un28txHvazWA4tcL6557mTgdTm2m/rjreBIpDKs99hMo1TztRM 2c9w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:from:to :content-language:user-agent:mime-version:date:message-id :ironport-sdr:dmarc-filter:delivered-to; bh=emPxPc9Syse6EduOKfUNcTYW1VFNCBvD/Om/nbpZb2A=; fh=qkNWUlRBZkew0ISI4uevDbSSAIG4eEcsJO0pUMvFaAo=; b=smDmWIykqH0ZYvH4haeQbSEEQ+/DXhNA9/T/cLqqMfeo+mSqbQp78jeImYJhDb0m1k 6kt7XYwxnEig6pUt9vOdr0RvjRL7X08WQNh4wQu7yy5st5NzKkDBU/A9gBf50xikcQE+ 7mvK2m4dPNx35j/4gsyCu9QDXf/zzYPZNphJkWunXCpKa/Jmn4nYT+FEHsztIBTT14GV LjrcO6KaIvfJoo6/+WkPcnVhVVqoBZnGW0geMF2+a7z0lC9fYBNlsor9tL/Ltz3aWOP/ bJ/v9+iprUOptP5E0ea7ryQrU9zkwkn5hmHSonTlmvIn7nCIhwumCaiLrNC7YbTrn3eo C0JA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org" Received: from server2.sourceware.org (server2.sourceware.org. [2620:52:3:1:0:246e:9693:128c]) by mx.google.com with ESMTPS id f22-20020a170906495600b009a1be9c8347si7542926ejt.496.2023.10.12.03.54.04 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 12 Oct 2023 03:54:04 -0700 (PDT) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) client-ip=2620:52:3:1:0:246e:9693:128c; Authentication-Results: mx.google.com; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org" Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id E5E693857737 for ; Thu, 12 Oct 2023 10:53:53 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa4.mentor.iphmx.com (esa4.mentor.iphmx.com [68.232.137.252]) by sourceware.org (Postfix) with ESMTPS id 396D83858CDB for ; Thu, 12 Oct 2023 10:53:26 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 396D83858CDB 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: 4dDTPhe/SpCMIQ5tBhi7aw== X-CSE-MsgGUID: wxjG+OxcRsuKdfsWFm0Ltg== X-IronPort-AV: E=Sophos;i="6.03,218,1694764800"; d="diff'?scan'208";a="19244694" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa4.mentor.iphmx.com with ESMTP; 12 Oct 2023 02:53:24 -0800 IronPort-SDR: 6//a0BFdSjNYDcTrxlVlPRmMcqarRbqX0DUTR+bhvMSSvGHO4RiQ4+k+NLs9JXhFgXjgRfkTcK Veahh07Yvn62zJFLTsOkCifnibESoiDtLCRoRNlZWE5QKj4iJoa4MCm6ET0K/NlWfBdnQ937eZ yCdR1eYRuOchv4kvAnV3GA1oIDNpLjCBG819ZJNOnL9CrdU8KtTfga/Vpnqr2Ct76+2XHa2xU9 ih/L3DJH4B7cZWWwGZbzrB8wwJPT3sTXym0URqyXojTXHfFLjYiMUGGQbjCEJyMVQxeeqeoXkr KcU= Message-ID: Date: Thu, 12 Oct 2023 12:53:19 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: gcc-patches , Sandra Loosemore , Jakub Jelinek From: Tobias Burnus Subject: [Patch] libgomp.texi: Note to 'Memory allocation' sect and missing mem-memory routines X-Originating-IP: [137.202.0.90] X-ClientProxiedBy: svr-ies-mbx-13.mgc.mentorg.com (139.181.222.13) 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, KAM_SHORT, 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+ouuuleilei=gmail.com@gcc.gnu.org X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1779546765247025735 X-GMAIL-MSGID: 1779546765247025735 This patch improves the documentation by completing the description of the remaining so far undocumented OpenMP Memory-Management Routines (except for the two function added in TR11, which are also unimplmeneted). Current online version: https://gcc.gnu.org/onlinedocs/libgomp/Memory-Management-Routines.html And the patch makes clearer when the OpenMP allocators are actually used; besides the obvious use via the routines above, it happens when using the 'allocate' directive/clause and the 'allocators' clause. The new note is added to the beginning of the section https://gcc.gnu.org/onlinedocs/libgomp/Memory-allocation.html The new note mostly applies, except that only C supports 'omp allocate'; Fortran has a patch pending a comment by Jakub and for C++ I still need to complete my daft patch. I also fixed some typos (albeit 'behaviour' is not really a typo), removed some 'kind=' for local consistency and to make especially the 'info' output cleaner. Comment, remarks, suggestions - before (or after) I apply it? Tobias PS: Also general comments and suggestions to the documentation are welcome. The wording (current patch and current documentation) can surely be improved. That documentation is missing - e.g. for several routines - is a known problem. If someone feels bored, besides reviewing libgomp.texi (6282 LoC), https://gcc.gnu.org/projects/gomp/ (1281 LoC) and https://gcc.gnu.org/wiki/Offloading (+ openmp + OpenACC) can surely be improved :-) ----------------- 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: Note to 'Memory allocation' sect and missing mem-memory routines This commit completes the documentation of the OpenMP memory-management routines, except for the unimplemented TR11 additions. It also makes clear in the 'Memory allocation' section of the 'OpenMP-Implementation Specifics' chapter under which condition OpenMP managed memory/allocators are used. libgomp/ChangeLog: * libgomp.texi: Fix some typos. (Memory Management Routines): Document remaining 5.x routines. (Memory allocation): Make clear when the section applies. libgomp/libgomp.texi | 382 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 367 insertions(+), 15 deletions(-) diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index 0d965f96d48..3fc9c7dea23 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -1917,7 +1917,7 @@ is not supported. @item @emph{Description}: If the device number is refers to the initial device or to a device with memory accessible from the host (shared memory), the @code{omp_get_mapped_ptr} -routines returnes the value of the passed @var{ptr}. Otherwise, if associated +routines returns the value of the passed @var{ptr}. Otherwise, if associated storage to the passed host pointer @var{ptr} exists on device associated with @var{device_num}, it returns that pointer. In all other cases and in cases of an error, a null pointer is returned. @@ -2397,12 +2397,12 @@ They have C linkage and do not throw exceptions. * 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:: -@c * omp_calloc:: -@c * omp_aligned_calloc:: -@c * omp_realloc:: +* omp_alloc:: Memory allocation with an allocator +* omp_aligned_alloc:: Memory allocation with an allocator and alignment +* omp_free:: Freeing memory allocated with OpenMP routines +* omp_calloc:: Allocate nullified memory with an allocator +* omp_aligned_calloc:: Allocate nullified aligned memory with an allocator +* omp_realloc:: Reallocate memory allocated with OpenMP routines @c * omp_get_memspace_num_resources:: /TR11 @c * omp_get_submemspace:: /TR11 @end menu @@ -2434,8 +2434,8 @@ may be used as trait value to specify that the default value should be used. @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 (omp_allocator_handle_kind) :: omp_init_allocator} +@item @tab @code{integer (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 @@ -2467,7 +2467,7 @@ routine is permitted but will have no effect. @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} +@item @tab @code{integer (omp_allocator_handle_kind), intent(in) :: allocator} @end multitable @item @emph{See also}: @@ -2495,7 +2495,7 @@ routine is invoked with the @code{omp_null_allocator} allocator. @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} +@item @tab @code{integer (omp_allocator_handle_kind), intent(in) :: allocator} @end multitable @item @emph{See also}: @@ -2524,7 +2524,7 @@ OpenMP memory routine is invoked with the @code{omp_null_allocator} allocator. @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} +@item @tab @code{integer (omp_allocator_handle_kind) :: omp_get_default_allocator} @end multitable @item @emph{See also}: @@ -2536,6 +2536,337 @@ OpenMP memory routine is invoked with the @code{omp_null_allocator} allocator. +@node omp_alloc +@subsection @code{omp_alloc} -- Memory allocation with an allocator +@table @asis +@item @emph{Description}: +Allocate memory with the specified allocator, which can either be a predefined +allocator, an allocator handle or @code{omp_null_allocator}. If the allocators +is @code{omp_null_allocator}, the allocator specified by the +@var{def-allocator-var} ICV is used. @var{size} must be a nonnegative number +denoting the number of bytes to be allocated; if @var{size} is zero, +@code{omp_alloc} will return a null pointer. If successful, a pointer to the +allocated memory is returned, otherwise the @code{fallback} trait of the +allocator determines the behavior. The content of the allocated memory is +unspecified. + +In @code{target} regions, either the @code{dynamic_allocators} clause must +appear on a @code{requires} directive in the same compilation unit -- or the +@var{allocator} argument may only be a constant expression with the value of +one of the predefined allocators and may not be @code{omp_null_allocator}. + +Memory allocated by @code{omp_alloc} must be freed using @code{omp_free}. + +@item @emph{C}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_alloc(size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator)} +@end multitable + +@item @emph{C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_alloc(size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator=omp_null_allocator)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{type(c_ptr) function omp_alloc(size, allocator) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only : c_ptr, c_size_t} +@item @tab @code{integer (c_size_t), value :: size} +@item @tab @code{integer (omp_allocator_handle_kind), value :: allocator} +@end multitable + +@item @emph{See also}: +@ref{OMP_ALLOCATOR}, @ref{Memory allocation}, @ref{omp_set_default_allocator}, +@ref{omp_free}, @ref{omp_init_allocator} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.7.6 +@end table + + + +@node omp_aligned_alloc +@subsection @code{omp_aligned_alloc} -- Memory allocation with an allocator and alignment +@table @asis +@item @emph{Description}: +Allocate memory with the specified allocator, which can either be a predefined +allocator, an allocator handle or @code{omp_null_allocator}. If the allocators +is @code{omp_null_allocator}, the allocator specified by the +@var{def-allocator-var} ICV is used. @var{alignment} must be a positive power +of two and @var{size} must be a nonnegative number that is a multiple of the +alignment and denotes the number of bytes to be allocated; if @var{size} is +zero, @code{omp_aligned_alloc} will return a null pointer. The alignment will +be at least the maximal value required by @code{alignment} trait of the +allocator and the value of the passed @var{alignment} argument. If successful, +a pointer to the allocated memory is returned, otherwise the @code{fallback} +trait of the allocator determines the behavior. The content of the allocated +memory is unspecified. + +In @code{target} regions, either the @code{dynamic_allocators} clause must +appear on a @code{requires} directive in the same compilation unit -- or the +@var{allocator} argument may only be a constant expression with the value of +one of the predefined allocators and may not be @code{omp_null_allocator}. + +Memory allocated by @code{omp_aligned_alloc} must be freed using +@code{omp_free}. + +@item @emph{C}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_aligned_alloc(size_t alignment,} +@item @tab @code{ size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator)} +@end multitable + +@item @emph{C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_aligned_alloc(size_t alignment,} +@item @tab @code{ size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator=omp_null_allocator)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{type(c_ptr) function omp_aligned_alloc(alignment, size, allocator) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only : c_ptr, c_size_t} +@item @tab @code{integer (c_size_t), value :: alignment, size} +@item @tab @code{integer (omp_allocator_handle_kind), value :: allocator} +@end multitable + +@item @emph{See also}: +@ref{OMP_ALLOCATOR}, @ref{Memory allocation}, @ref{omp_set_default_allocator}, +@ref{omp_free}, @ref{omp_init_allocator} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.13.6 +@end table + + + +@node omp_free +@subsection @code{omp_free} -- Freeing memory allocated with OpenMP routines +@table @asis +@item @emph{Description}: +The @code{omp_free} routine deallocates memory previously allocated by an +OpenMP memory-management routine. The @var{ptr} argument must point to such +memory or be a null pointer; if it is a null pointer, no operation is +performed. If specified, the @var{allocator} argument must be either the +memory allocator that was used for the allocation or @code{omp_null_allocator}; +if it is @code{omp_null_allocator}, the implementation will determine the value +automatically. + +Calling @code{omp_free} invokes undefined behavior if the memory +was already deallocated or when the used allocator has already been destroyed. + +@item @emph{C}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void omp_free(void *ptr,} +@item @tab @code{ omp_allocator_handle_t allocator)} +@end multitable + +@item @emph{C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void omp_free(void *ptr,} +@item @tab @code{ omp_allocator_handle_t allocator=omp_null_allocator)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{subroutine omp_free(ptr, allocator) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only : c_ptr} +@item @tab @code{type (c_ptr), value :: ptr} +@item @tab @code{integer (omp_allocator_handle_kind), value :: allocator} +@end multitable + +@item @emph{See also}: +@ref{omp_alloc}, @ref{omp_aligned_alloc}, @ref{omp_calloc}, +@ref{omp_aligned_calloc}, @ref{omp_realloc} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.7.7 +@end table + + + +@node omp_calloc +@subsection @code{omp_calloc} -- Allocate nullified memory with an allocator +@table @asis +@item @emph{Description}: +Allocate zero-initialized memory with the specified allocator, which can either +be a predefined allocator, an allocator handle or @code{omp_null_allocator}. If +the allocators is @code{omp_null_allocator}, the allocator specified by the +@var{def-allocator-var} ICV is used. The to-be allocated memory is for an +array with @var{nmemb} elements, each having a size of @var{size} bytes. Both +@var{nmemb} and @var{size} must be nonnegative numbers; if either of them is +zero, @code{omp_calloc} will return a null pointer. If successful, a pointer to +the zero-initialized allocated memory is returned, otherwise the @code{fallback} +trait of the allocator determines the behavior. + +In @code{target} regions, either the @code{dynamic_allocators} clause must +appear on a @code{requires} directive in the same compilation unit -- or the +@var{allocator} argument may only be a constant expression with the value of +one of the predefined allocators and may not be @code{omp_null_allocator}. + +Memory allocated by @code{omp_calloc} must be freed using @code{omp_free}. + +@item @emph{C}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_calloc(size_t nmemb, size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator)} +@end multitable + +@item @emph{C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_calloc(size_t nmemb, size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator=omp_null_allocator)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{type(c_ptr) function omp_calloc(nmemb, size, allocator) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only : c_ptr, c_size_t} +@item @tab @code{integer (c_size_t), value :: nmemb, size} +@item @tab @code{integer (omp_allocator_handle_kind), value :: allocator} +@end multitable + +@item @emph{See also}: +@ref{OMP_ALLOCATOR}, @ref{Memory allocation}, @ref{omp_set_default_allocator}, +@ref{omp_free}, @ref{omp_init_allocator} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.13.8 +@end table + + + +@node omp_aligned_calloc +@subsection @code{omp_aligned_calloc} -- Allocate aligned nullified memory with an allocator +@table @asis +@item @emph{Description}: +Allocate zero-initialized memory with the specified allocator, which can either +be a predefined allocator, an allocator handle or @code{omp_null_allocator}. If +the allocators is @code{omp_null_allocator}, the allocator specified by the +@var{def-allocator-var} ICV is used. The to-be allocated memory is for an +array with @var{nmemb} elements, each having a size of @var{size} bytes. Both +@var{nmemb} and @var{size} must be nonnegative numbers; if either of them is +zero, @code{omp_aligned_calloc} will return a null pointer. @var{alignment} +must be a positive power of two and @var{size} must be a multiple of the +alignment; the alignment will be at least the maximal value required by +@code{alignment} trait of the allocator and the value of the passed +@var{alignment} argument. If successful, a pointer to the zero-initialized +allocated memory is returned, otherwise the @code{fallback} trait of the +allocator determines the behavior. + +In @code{target} regions, either the @code{dynamic_allocators} clause must +appear on a @code{requires} directive in the same compilation unit -- or the +@var{allocator} argument may only be a constant expression with the value of +one of the predefined allocators and may not be @code{omp_null_allocator}. + +Memory allocated by @code{omp_aligned_calloc} must be freed using +@code{omp_free}. + +@item @emph{C}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_aligned_calloc(size_t nmemb, size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator)} +@end multitable + +@item @emph{C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_aligned_calloc(size_t nmemb, size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator=omp_null_allocator)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{type(c_ptr) function omp_aligned_calloc(nmemb, size, allocator) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only : c_ptr, c_size_t} +@item @tab @code{integer (c_size_t), value :: nmemb, size} +@item @tab @code{integer (omp_allocator_handle_kind), value :: allocator} +@end multitable + +@item @emph{See also}: +@ref{OMP_ALLOCATOR}, @ref{Memory allocation}, @ref{omp_set_default_allocator}, +@ref{omp_free}, @ref{omp_init_allocator} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.13.8 +@end table + + + +@node omp_realloc +@subsection @code{omp_realloc} -- Reallocate memory allocated with OpenMP routines +@table @asis +@item @emph{Description}: +The @code{omp_realloc} routine deallocates memory to which @var{ptr} points to +and allocates new memory with the specified @var{allocator} argument; the +new memory will have the content of the old memory up to the minimum of the +old size and the new @var{size}, otherwise the content of the returned memory +is unspecified. If the new allocator is the same as the old one, the routine +tries to resize the existing memory allocation, returning the same address as +@var{ptr} if successful. @var{ptr} must point to memory allocated by an OpenMP +memory-management routine. + +The @var{allocator} and @var{free_allocator} arguments must be a predefined +allocator, an allocator handle or @code{omp_null_allocator}. If +@var{free_allocator} is @code{omp_null_allocator}, the implementation +automatically determines the allocator used for the allocation of @var{ptr}. +If @var{allocator} is @code{omp_null_allocator} and @var{ptr} is is not a +null pointer, the same allocator as @code{free_allocator} is used and +when @var{ptr} is a null pointer the allocator specified by the +@var{def-allocator-var} ICV is used. + +The @var{size} must be a nonnegative number denoting the number of bytes to be +allocated; if @var{size} is zero, @code{omp_realloc} will return free the +memory and return a null pointer. When @var{size} is nonzero: if successful, +a pointer to the allocated memory is returned, otherwise the @code{fallback} +trait of the allocator determines the behavior. + +In @code{target} regions, either the @code{dynamic_allocators} clause must +appear on a @code{requires} directive in the same compilation unit -- or the +@var{free_allocator} and @var{allocator} arguments may only be a constant +expression with the value of one of the predefined allocators and may not be +@code{omp_null_allocator}. + +Memory allocated by @code{omp_realloc} must be freed using @code{omp_free}. +Calling @code{omp_free} invokes undefined behavior if the memory +was already deallocated or when the used allocator has already been destroyed. + +@item @emph{C}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_realloc(void *ptr, size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator,} +@item @tab @code{ omp_allocator_handle_t free_allocator)} +@end multitable + +@item @emph{C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void* omp_realloc(void *ptr, size_t size,} +@item @tab @code{ omp_allocator_handle_t allocator=omp_null_allocator,} +@item @tab @code{ omp_allocator_handle_t free_allocator=omp_null_allocator)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{type(c_ptr) function omp_realloc(ptr, size, allocator, free_allocator) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only : c_ptr, c_size_t} +@item @tab @code{type(C_ptr), value :: ptr} +@item @tab @code{integer (c_size_t), value :: size} +@item @tab @code{integer (omp_allocator_handle_kind), value :: allocator, free_allocator} +@end multitable + +@item @emph{See also}: +@ref{OMP_ALLOCATOR}, @ref{Memory allocation}, @ref{omp_set_default_allocator}, +@ref{omp_free}, @ref{omp_init_allocator} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.7.9 +@end table + + + @c @node Tool Control Routine @c @c FIXME @@ -2591,7 +2922,7 @@ variable is not set. * OMP_PLACES:: Specifies on which CPUs the threads should be placed * OMP_STACKSIZE:: Set default thread stack size * OMP_SCHEDULE:: How threads are scheduled -* OMP_TARGET_OFFLOAD:: Controls offloading behaviour +* OMP_TARGET_OFFLOAD:: Controls offloading behavior * OMP_TEAMS_THREAD_LIMIT:: Set the maximum number of threads imposed by teams * OMP_THREAD_LIMIT:: Set the maximum number of threads * OMP_WAIT_POLICY:: How waiting threads are handled @@ -3121,14 +3452,14 @@ dynamic scheduling and a chunk size of 1 is used. @node OMP_TARGET_OFFLOAD -@section @env{OMP_TARGET_OFFLOAD} -- Controls offloading behaviour +@section @env{OMP_TARGET_OFFLOAD} -- Controls offloading behavior @cindex Environment Variable @cindex Implementation specific setting @table @asis @item @emph{ICV:} @var{target-offload-var} @item @emph{Scope:} global @item @emph{Description}: -Specifies the behaviour with regard to offloading code to a device. This +Specifies the behavior with regard to offloading code to a device. This variable can be set to one of three values - @code{MANDATORY}, @code{DISABLED} or @code{DEFAULT}. @@ -5282,6 +5613,27 @@ on more architectures, GCC currently does not match any @code{arch} or @node Memory allocation @section Memory allocation +The description below applies to: + +@itemize +@item Explicit use of the OpenMP API routines, see + @ref{Memory Management Routines}. +@item The @code{allocate} clause, except when the @code{allocator} modifier is a + constant expression with value @code{omp_default_mem_alloc} and no + @code{align} modifier has been specified. (In that case, the normal + @code{malloc} allocation is used.) +@item Using the @code{allocate} directive for automatic/stack variables, except + when the @code{allocator} clause is a constant expression with value + @code{omp_default_mem_alloc} and no @code{align} clause has been + specified. (In that case, the normal allocation is used: stack allocation + and, sometimes for Fortran, also @code{malloc} [depending on flags such as + @option{-fstack-arrays}].) +@item Using the @code{allocate} directive for variable in static memory is + currently not supported (compile time error). +@item Using the @code{allocators} directive for Fortran pointers and + allocatables is currently not supported (compile time error). +@end itemize + For the available predefined allocators and, as applicable, their associated predefined memory spaces and for the available traits and their default values, see @ref{OMP_ALLOCATOR}. Predefined allocators without an associated memory