\input texinfo
@c %**start of header
@setfilename parallel.info
@settitle parallel_doc
@c %**end of header

@c Nowadays the predined function index has entries for each @deftypefn
@c in additiont to each @findex.
@defcodeindex mfn

@copying
General documentation for the parallel package for Octave.

Copyright @copyright{} 2016-2023 @email{Olaf Till <i7tiol@@t-online.de>}

You can redistribute this documentation and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation; either version 3 of the License, or (at your option) any
later version.

This documentation is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along
with this documentation; if not, see <http://www.gnu.org/licenses/>.
@end copying

@include macros.texi

@macro mysee
@ifhtml
see
@end ifhtml
@end macro

@ifinfo
@dircategory Math
@direntry
* Octave parallel: (parallel).                 Parallel package of Octave.
@end direntry
@end ifinfo

@titlepage
@title General documentation for the documentation package for Octave
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c No table of contents. The table would occupy most of the top node in
@c html and IMHO misleads the user to use the table instead of the menu
@c structure of the nodes, which would let some information unused.
@c
@c @contents

@c ------------------------------------------------------------------

@node Top
@top General documentation for the parallel package for Octave

@ifhtml
The info version of this document is accessible, after package
installation, from the Octave commandline with @code{parallel_doc()}.
@end ifhtml

This documentation applies to version @PACKAGEVERSION of the parallel
package.

The package contains functions for explicit local parallel execution
and functions for parallel execution over a cluster of machines,
possibly combined with local parallel execution at each machine of the
cluster.

Earlier versions of the package used Octave sessions directly
generated by the @code{fork} system call. Since this causes problems,
the current version uses newly started Octave sessions, even for local
parallel execution. This causes some limitations, see
@ref{Limitations}.

The server for cluster execution is installed at GNU/Linux, but not at
some other operating systems, e.g. not at Windows or macOS. The client
functions for cluster execution should be installed at all systems,
though.

@menu
* Installation::                Installation hints.
* Local execution::             Functions for local parallel execution.
* Cluster execution::           Functions for parallel execution over a
                                  cluster of machines.
* Further functions::           Functions possibly helpful in parallel
                                  execution.
* Limitations::                 Limitations of high- and
                                  medium-level functions.

* Documentation::               Function parallel_doc to view
                                  documentation.

Indices
* Function index::              Index of functions in database.
* Concept index::               Concept index.
@end menu

@c ------------------------------------------------------------------

@node Installation
@chapter Installation hints
@cindex installation

@emph{Note:} For using a cluster of machines, identical versions of the
package are required to be installed at each machine.

Maybe your distribution provides the parallel package.

If not, or if you want a newer version, Octaves @code{pkg} command
allows building the package from source and installing it. Note that you
have to @code{load} any Octave package before you can use it. See
Octaves documentation of @code{pkg}.

Parallel execution over a cluster by default is protected by encryption
with authentication. This needs a version of the gnutls library in which
TLS-SRP is not disabled. For building the parallel package from source,
this library must be present during the build; some operating systems
provide development files of libraries in exta @code{...-dev} packages,
which are also needed during the build.

Building or using the package for cluster execution without gnutls will
work, but encryption and authentication are not available in this case.

@c ------------------------------------------------------------------

@node Local execution
@chapter Functions for local parallel execution
@cindex local execution

Explicit local parallel execution, with the intent to exploit more than
one local processor(-core), is performed by calling a user-defined
function in parallel with several different arguments. This is done in
parallel @emph{processes}. Note that there is no way to pass global
variables to or from these processes.

The interface of the functions for local parallel execution is similar
to Octaves @code{cellfun} and @code{arrayfun} functions.

Note that some operations in Octave, particularly some matrix
operations, may already be performed in parallel threads. This may limit
the advantage yielded by explicit local parallel execution. Also, RAM
access can be a bottleneck which limits computation speed of multicore
computing.

For limitations, see @ref{Limitations}.

@menu
* parcellfun::                        Function parcellfun.
* pararrayfun::                       Function pararrayfun.
* parcellfun_set_nproc::              Function parcellfun_set_nproc::
@end menu

@c ------------------------------------------------------------------

@node parcellfun
@section Function parcellfun
@mfnindex parcellfun

@c include function helptext here
@DOCSTRING(parcellfun)

@c ------------------------------------------------------------------

@node pararrayfun
@section Function pararrayfun
@mfnindex pararrayfun

@c include function helptext here
@DOCSTRING(pararrayfun)

See also @ref{XREFparcellfun,,parcellfun},
@ref{XREFarrayfun,,arrayfun,octave}.

@c ------------------------------------------------------------------

@node parcellfun_set_nproc
@section Function parcellfun_set_nproc
@mfnindex parcellfun_set_nproc

@c include function helptext here
@DOCSTRING(parcellfun_set_nproc)

@c ------------------------------------------------------------------

@node Cluster execution
@chapter Functions for parallel execution over a cluster of machines
@cindex cluster execution

There are high level functions, similar to @ref{parcellfun} and
@ref{pararrayfun}, which only require the user to provide a function to
be called and a series of argument sets. Parallel function calls are
then internally distributed over the cluster, and over the local
processors (or processor cores) within the single machines of the
cluster.

Medium and low level functions are also provided. These require the user
to program the scheduling of parallel execution.

Data transfer is possible between the client machine and each server
machine, but also directly between server machines. The latter feature
is exploited e.g. by the @ref{install_vars} function.

For limitations, see @ref{Limitations}.

@menu
* Security::                        Security considerations.
* Authentication::                  Generating authentication keys.
* pserver::                         Starting servers.

Connection-related functions
* pconnect::                        Establishing cluster connections.
* sclose::                          Closing cluster connections.
* network_get_info::                Get network information.
* network_set::                     Set network properties.

High level functions
* netcellfun::                      Function netcellfun.
* netarrayfun::                     Function netarrayfun.
* install_vars::                    Distribute Octave variables.

Medium level functions
* rfeval::                          Single remote function evaluation.

Low level functions
* psend::                           Sending Octave variables.
* precv::                           Receiving Octave variables.
* reval::                           Remote command evaluation.
* select_sockets::                  Call Unix @code{select} for data
                                      connections.

* Example::                         Example
@end menu

@c ------------------------------------------------------------------

@node Security
@section Security considerations
@cindex security

Over a connection to a server of the parallel package arbitrary Octave
commands can be executed at the server machine. This means that any
change can be done to the server system and the resident data, only
limited by the rights of the system account under which the server runs.

By default, the server is started with authentication and encryption
enabled, to avoid unauthorized access. If the server is started with
authentication disabled (maybe to avoid the encryption overhead), it
must be cared for that no TCP connection by unauthorized persons is
possible to the server ports, possibly by running the client and all
server machines behind a firewall and assuring that only trusted persons
have access to any machine behind the firewall. This scenario might be
achievable in home-nets.

The server currently uses port 12502 for receiving commands and port
12501 for data exchange.

The client and the servers used by the client with @code{pconnect} must
agree on using authentication or not.

Do not start the server as root.

@c ------------------------------------------------------------------

@node Authentication
@section Generating authentication keys
@cindex authentication
@mfnindex parallel_generate_srp_data

@c include function helptext here
@DOCSTRING(parallel_generate_srp_data)

@c ------------------------------------------------------------------

@node pserver
@section Starting servers
@mfnindex pserver

@c include function helptext here
@DOCSTRING(pserver)

@c ------------------------------------------------------------------

@node pconnect
@section Establishing cluster connections
@mfnindex pconnect

@c include function helptext here
@DOCSTRING(pconnect)

@c ------------------------------------------------------------------

@node sclose
@section Closing cluster connections
@mfnindex sclose

@c include function helptext here
@DOCSTRING(sclose)

@c ------------------------------------------------------------------

@node network_get_info
@section Get network information
@mfnindex network_get_info

@c include function helptext here
@DOCSTRING(network_get_info)

@c ------------------------------------------------------------------

@node network_set
@section Set network properties
@mfnindex network_set

@c include function helptext here
@DOCSTRING(network_set)

@c ------------------------------------------------------------------

@node netcellfun
@section Function netcellfun
@mfnindex netcellfun

@c include function helptext here
@DOCSTRING(netcellfun)

@c ------------------------------------------------------------------

@node netarrayfun
@section Function netarrayfun
@mfnindex netarrayfun

@c include function helptext here
@DOCSTRING(netarrayfun)

@c ------------------------------------------------------------------

@node install_vars
@section Distribute Octave variables
@mfnindex install_vars

@c include function helptext here
@DOCSTRING(install_vars)

@c ------------------------------------------------------------------

@node rfeval
@section Single remote function evaluation
@mfnindex rfeval

@c include function helptext here
@DOCSTRING(rfeval)

@c ------------------------------------------------------------------

@node psend
@section Sending Octave variables
@mfnindex psend

@c include function helptext here
@DOCSTRING(psend)

@c ------------------------------------------------------------------

@node precv
@section Receiving Octave variables
@mfnindex precv

@c include function helptext here
@DOCSTRING(precv)

@c ------------------------------------------------------------------

@node reval
@section Remote command evaluation
@mfnindex reval

@c include function helptext here
@DOCSTRING(reval)

@c ------------------------------------------------------------------

@node select_sockets
@section Call Unix @code{select} for data connections
@mfnindex select sockets

@c include function helptext here
@DOCSTRING(select_sockets)

@c ------------------------------------------------------------------

@node Example
@section Example
@cindex example

@example

# From Octave prompt, generate authentication files, set user name to
# 'test'. When prompted for a password, press <enter>.
parallel_generate_srp_data ('test')

# From Octave prompt, get location of the generated files.
authpath = fullfile (a = pkg ("prefix"), "parallel-srp-data")

Copy server files to servers, authpath is assumed to be
"/home/test/octave/parallel-srp-data/", the same directory is assumed to
exist on the servers. From the system shell, do e.g.:

scp -r /home/test/octave/parallel-srp-data/server server1:/home/test/octave/parallel-srp-data/
scp -r /home/test/octave/parallel-srp-data/server server2:/home/test/octave/parallel-srp-data/

Start server at remote machines. From the system shell, do e.g.:

ssh server1 'octave --eval "pserver"'
ssh server2 'octave --eval "pserver"'

# From Octave prompt, connect the cluster.
conns = pconnect (@{"server1", "server2"@})

# And perform some parallel execution. Single function calls take 1
# second each.
results = netcellfun (conns, @ (x) @{x, pause(1)@}@{:@}, num2cell (1:30))

# Close network.
sclose (conns)

@end example

@c ------------------------------------------------------------------

@node Further functions
@chapter Functions possibly helpful in parallel execution

@menu
* fsave fload::                 Transfer variable within the local
                                  machine over an Octave stream.
* select::                      Call Unix @code{select} on Octave
                                  streams.
@end menu

@c ------------------------------------------------------------------

@node fsave fload
@section Transfer variable within the local machine over an Octave stream
@mfnindex fsave
@mfnindex fload

@c include function helptext here
@DOCSTRING(fsave)

@c include function helptext here
@DOCSTRING(fload)

@c ------------------------------------------------------------------

@node select
@section Call Unix @code{select} on Octave streams
@mfnindex select

Note that for cluster connections @ref{select_sockets} should be used
instead.

@c include function helptext here
@DOCSTRING(select)

@c ------------------------------------------------------------------

@node Limitations
@chapter Limitations of high- and medium-level functions
@cindex limitations

Note that @ref{netcellfun}, @ref{netarrayfun}, and @ref{rfeval}, but
even @ref{parcellfun} and @ref{pararrayfun}, execute code in separate
Octave processes. This causes some limitations.

For the function handles passed as arguments to @ref{parcellfun},
@ref{pararrayfun}, @ref{netcellfun}, @ref{netarrayfun}, and
@ref{rfeval}, the following limitations may apply:

@itemize
@item In Octave versions before 5.1, anonymous functions may only be
passed if they don't use @code{varargin} and don't contain nested
anonymous functions.
@item If a handle to a named function, written in a function file,
is passed, this function must exist on the server machine. This is
usually no problem for @ref{parcellfun} and @ref{pararrayfun}.
@item Named functions defined in the command line interface or by
scripts are not exported to the working sessions used by
@ref{parcellfun} or @ref{pararrayfun}, and not automatically to the
server for remote parallel execution.
@item For handles to subfunctions or to private functions limitations
depending on the used Octave version may apply.
@end itemize

Anonymous functions should be usable as usual, since the function
specification sent to the server will include the anonymous functions
context.

If @ref{parcellfun} or @ref{pararrayfun} (and of course the
cluster-related functions, too) are called from within a function with
subfunctions, the subfunctions won't be visible in parallel execution.

There is no way to set global variables for the function called by
@code{parcellun} or @code{pararrayfun}. For cluster execution, setting
global variables is possible, e.g. with @ref{install_vars}; however,
@code{netcellfun} and @code{netarrayfun} won't 'see' global variables if
they use @code{parcellfun} internally (which is the default at remote
machines with more than one available processor core).

@c ------------------------------------------------------------------

@node Documentation
@chapter Function parallel_doc to view documentation
@cindex documentation
@mfnindex parallel_doc

@c include function helptext here
@DOCSTRING(parallel_doc)

@c ------------------------------------------------------------------

@node Function index
@unnumbered Index of functions in parallel

@printindex mfn

@c ------------------------------------------------------------------

@node Concept index
@unnumbered Concept index

@printindex cp

@bye