FreeChainXenon/gcc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

gfortran.texi (Coarray Programming): Add first ABI documentation.

Browse source 
2014-08-14  Tobias Burnus  <burnus@net-b.de>

        * gfortran.texi (Coarray Programming): Add first ABI
        documentation.

From-SVN: r213978
This commit is contained in:
Tobias Burnus 2014-08-14 20:35:01 +02:00 • committed by Tobias Burnus
parent 9c8d7ac2a3
commit c194537c63
2 changed files with 380 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
gcc/fortran/ChangeLog
View file

@ -1,3 +1,8 @@
2014-08-14 Tobias Burnus <burnus@net-b.de>
* gfortran.texi (Coarray Programming): Add first ABI
documentation.
2014-08-14 Jakub Jelinek <jakub@redhat.com>
PR fortran/62076

375
gcc/fortran/gfortran.texi
View file

@ -184,6 +184,7 @@ Part II: Language Reference
* Compiler Characteristics:: User-visible implementation details.
* Extensions:: Language extensions implemented by GNU Fortran.
* Mixed-Language Programming:: Interoperability with C
* Coarray Programming::
* Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
* Intrinsic Modules:: Intrinsic modules supported by GNU Fortran.
@ -3176,6 +3177,380 @@ of such a type
@end itemize
@c ---------------------------------------------------------------------
@c Coarray Programming
@c ---------------------------------------------------------------------
@node Coarray Programming
@chapter Coarray Programming
@cindex Coarrays
@menu
* Type and enum ABI Documentation::
* Function ABI Documentation::
@end menu
@node Type and enum ABI Documentation
@section Type and enum ABI Documentation
@menu
* caf_token_t::
* caf_register_t::
@end menu
@node caf_token_t
@subsection @code{caf_token_t}
Typedef of type @code{void *} on the compiler side. Can be any data
type on the library side.
@node caf_register_t
@subsection @code{caf_register_t}
Indicates which kind of coarray variable should be registered.
@verbatim
typedef enum caf_register_t {
CAF_REGTYPE_COARRAY_STATIC,
CAF_REGTYPE_COARRAY_ALLOC,
CAF_REGTYPE_LOCK_STATIC,
CAF_REGTYPE_LOCK_ALLOC
}
caf_register_t;
@end verbatim
@node Function ABI Documentation
@section Function ABI Documentation
@menu
* _gfortran_caf_init:: Initialiation function
* _gfortran_caf_finish:: Finalization function
* _gfortran_caf_this_image:: Querying the image number
* _gfortran_caf_num_images:: Querying the maximal number of images
* _gfortran_caf_register:: Registering coarrays
* _gfortran_caf_deregister:: Deregistering coarrays
* _gfortran_caf_send:: Sending data from a local image to a remote image
* _gfortran_caf_get:: Getting data from a remote image
* _gfortran_caf_sendget:: Sending data between remote images
@end menu
@node _gfortran_caf_init
@subsection @code{_gfortran_caf_init} --- Initialiation function
@cindex Coarray, _gfortran_caf_init
@table @asis
@item @emph{Description}:
This function is called at startup of the program before the Fortran main
program, if the latter has been compiled with @option{-fcoarray=lib}.
It takes as arguments the command-line arguments of the program. It is
permitted to pass to @code{NULL} pointers as argument; if non-@code{NULL},
the library is permitted to modify the arguments.
@item @emph{Syntax}:
@code{void _gfortran_caf_init (int *argc, char ***argv)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{argc} @tab intent(inout) An integer pointer with the number of
arguments passed to the program or @code{NULL}.
@item @var{argv} @tab intent(inout) A pointer to an array of strings with the
command-line arguments or @code{NULL}.
@end multitable
@item @emph{NOTES}
The function is modelled after the initialization function of the Message
Passing Interface (MPI) specification. Due to the way coarray registration
works, it might not be the first call to the libaray. If the main program is
not written in Fortran and only a library uses coarrays, it can happen that
this function is never called. Therefore, it is recommended that the library
does not rely on the passed arguments and whether the call has been done.
@end table
@node _gfortran_caf_finish
@subsection @code{_gfortran_caf_finish} --- Finalization function
@cindex Coarray, _gfortran_caf_finish
@table @asis
@item @emph{Description}:
This function is called at the end of the Fortran main program, if it has
been compiled with the @option{-fcoarray=lib} option.
@item @emph{Syntax}:
@code{void _gfortran_caf_finish (void)}
@item @emph{NOTES}
For non-Fortran programs, it is recommended to call the function at the end
of the main program. To ensure that the shutdown is also performed for
programs where this function is not explicitly invoked, for instance
non-Fortran programs or calls to the system's exit() function, the library
can use a destructor function. Note that programs can also be terminated
using the STOP and ERROR STOP statements; those use different library calls.
@end table
@node _gfortran_caf_this_image
@subsection @code{_gfortran_caf_this_image} --- Querying the image number
@cindex Coarray, _gfortran_caf_this_image
@table @asis
@item @emph{Description}:
This function returns the current image number, which is a positive number.
@item @emph{Syntax}:
@code{int _gfortran_caf_this_image (int distance)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{distance} @tab As specified for the @code{this_image} intrinsic
in TS18508. Shall be a nonnegative number.
@end multitable
@item @emph{NOTES}
If the Fortran intrinsic @code{this_image} is invoked without an argument, which
is the only permitted form in Fortran 2008, GCC passes @code{0} as
first argument.
@end table
@node _gfortran_caf_num_images
@subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
@cindex Coarray, _gfortran_caf_num_images
@table @asis
@item @emph{Description}:
This function returns the number of images in the current team, if
@var{distance} is 0 or the number of images in the parent team at the specified
distance. If failed is -1, the function returns the number of all images at
the specified distance; if it is 0, the function returns the number of
nonfailed images, and if it is 1, it returns the number of failed images.
@item @emph{Syntax}:
@code{int _gfortran_caf_num_images(int distance, int failed)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{distance} @tab the distance from this image to the ancestor.
Shall be positive.
@item @var{failed} @tab shall be -1, 0, or 1
@end multitable
@item @emph{NOTES}
This function follows TS18508. If the num_image intrinsic has no arguments,
the the compiler passes @code{distance=0} and @code{failed=-1} to the function.
@end table
@node _gfortran_caf_register
@subsection @code{_gfortran_caf_register} --- Registering coarrays
@cindex Coarray, _gfortran_caf_deregister
@table @asis
@item @emph{Description}:
Allocates memory for a coarray and creates a token to identify the coarray. The
function is called for both coarrays with @code{SAVE} attribute and using an
explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
@code{NULL} pointer, the function shall abort with printing an error message
and starting the error termination. If no error occurs and @var{STAT} is
present, it shall be set to zero. Otherwise, it shall be set to a positive
value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
the failure. The function shall return a pointer to the requested memory
for the local image as a call to @code{malloc} would do.
@item @emph{Syntax}:
@code{void *caf_register (size_t size, caf_register_t type, caf_token_t *token,
int *stat, char *errmsg, int errmsg_len)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{size} @tab byte size of the coarray to be allocated
@item @var{type} @tab one of the caf_register_t types.
@item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=; may be NULL
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to an error message; may be NULL
@item @var{errmsg_len} @tab the buffer size of errmsg.
@end multitable
@item @emph{NOTES}
Nonalloatable coarrays have to be registered prior use from remote images.
In order to guarantee this, they have to be registered before the main
program. This can be achieved by creating constructor functions. That is what
GCC does such that also nonallocatable coarrays the memory is allocated and no
static memory is used. The token permits to identify the coarray; to the
processor, the token is a nonaliasing pointer. The library can, for instance,
store the base address of the coarray in the token, some handle or a more
complicated struct.
@end table
@node _gfortran_caf_deregister
@subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
@cindex Coarray, _gfortran_caf_deregister
@table @asis
@item @emph{Description}:
Called to free the memory of a coarray; the processor calls this function for
automatic and explicit deallocation. In case of an error, this function shall
fail with an error message, unless the @var{STAT} variable is not null.
@item @emph{Syntax}:
@code{void caf_deregister (const caf_token_t *token, int *stat, char *errmsg,
int errmsg_len)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=; may be NULL
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to an error message; may be NULL
@item @var{errmsg_len} @tab the buffer size of errmsg.
@end multitable
@item @emph{NOTES}
For nonalloatable coarrays this function is never called. If a cleanup is
required, it has to be handled via the finish, stop and error stop functions,
and via destructors.
@end table
@node _gfortran_caf_send
@subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
@cindex Coarray, _gfortran_caf_send
@table @asis
@item @emph{Description}:
Called to send a scalar, an array section or whole array from a local
to a remote image identified by the image_index.
@item @emph{Syntax}:
@code{void _gfortran_caf_send (caf_token_t token, size_t offset,
int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
gfc_descriptor_t *src, int dst_kind, int src_kind)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
@item @var{offset} @tab By which amount of bytes the actual data is shifted
compared to the base address of the coarray.
@item @var{image_index} @tab The ID of the remote image; must be a positive
number.
@item @var{dest} @tab intent(in) Array descriptor for the remote image for the
bounds and the size. The base_addr shall not be accessed.
@item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
subscript of the destination array; the values are relative to the dimension
triplet of the dest argument.
@item @var{src} @tab intent(in) Array descriptor of the local array to be
transferred to the remote image
@item @var{dst_kind} @tab Kind of the destination argument
@item @var{src_kind} @tab Kind of the source argument
@end multitable
@item @emph{NOTES}
It is permitted to have image_id equal the current image; the memory of the
send-to and the send-from might (partially) overlap in that case. The
implementation has to take care that it handles this case. Note that the
assignment of a scalar to an array is permitted. In addition, the library has
to handle numeric-type conversion and for strings, padding and different
character kinds.
@end table
@node _gfortran_caf_get
@subsection @code{_gfortran_caf_get} --- Getting data from a remote image
@cindex Coarray, _gfortran_caf_get
@table @asis
@item @emph{Description}:
Called to get an array section or whole array from a a remote,
image identified by the image_index.
@item @emph{Syntax}:
@code{void _gfortran_caf_get_desc (caf_token_t token, size_t offset,
int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
gfc_descriptor_t *dest, int src_kind, int dst_kind)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
@item @var{offset} @tab By which amount of bytes the actual data is shifted
compared to the base address of the coarray.
@item @var{image_index} @tab The ID of the remote image; must be a positive
number.
@item @var{dest} @tab intent(in) Array descriptor of the local array to be
transferred to the remote image
@item @var{src} @tab intent(in) Array descriptor for the remote image for the
bounds and the size. The base_addr shall not be accessed.
@item @var{src_vector} @tab intent(int) If not NULL, it contains the vector
subscript of the destination array; the values are relative to the dimension
triplet of the dest argument.
@item @var{dst_kind} @tab Kind of the destination argument
@item @var{src_kind} @tab Kind of the source argument
@end multitable
@item @emph{NOTES}
It is permitted to have image_id equal the current image; the memory of the
send-to and the send-from might (partially) overlap in that case. The
implementation has to take care that it handles this case. Note that the
library has to handle numeric-type conversion and for strings, padding
and different character kinds.
@end table
@node _gfortran_caf_sendget
@subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
@cindex Coarray, _gfortran_caf_sendget
@table @asis
@item @emph{Description}:
Called to send a scalar, an array section or whole array from a remote image
identified by the src_image_index to a remote image identified by the
dst_image_index.
@item @emph{Syntax}:
@code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
caf_token_t src_token, size_t src_offset, int src_image_index,
gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{dst_token} @tab intent(in) An opaque pointer identifying the
destination coarray.
@item @var{dst_offset} @tab By which amount of bytes the actual data is
shifted compared to the base address of the destination coarray.
@item @var{dst_image_index} @tab The ID of the destination remote image; must
be a positive number.
@item @var{dst_dest} @tab intent(in) Array descriptor for the destination
remote image for the bounds and the size. The base_addr shall not be accessed.
@item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
subscript of the destination array; the values are relative to the dimension
triplet of the dest argument.
@item @var{src_token} @tab An opaque pointer identifying the source coarray.
@item @var{src_offset} @tab By which amount of bytes the actual data is shifted
compared to the base address of the source coarray.
@item @var{src_image_index} @tab The ID of the source remote image; must be a
positive number.
@item @var{src_dest} @tab intent(in) Array descriptor of the local array to be
transferred to the remote image.
@item @var{src_vector} @tab intent(in) Array descriptor of the local array to
be transferred to the remote image
@item @var{dst_kind} @tab Kind of the destination argument
@item @var{src_kind} @tab Kind of the source argument
@end multitable
@item @emph{NOTES}
It is permitted to have image_id equal the current image; the memory of the
send-to and the send-from might (partially) overlap in that case. The
implementation has to take care that it handles this case. Note that the
assignment of a scalar to an array is permitted. In addition, the library has
to handle numeric-type conversion and for strings, padding and different
character kinds.
@end table
@c Intrinsic Procedures
@c ---------------------------------------------------------------------