[Swift-devel] User perspective on how an app procedure call maps into an application executable call

[Ben Clifford]

I wrote the below in an attempt to document what I percieve to be the key 
user percieved behaviour of how an app procedure call in SwiftScript is 
executed on a worker. This is distinct from how the present implementation 
causes the below to actually happen - I plan to write a related note for 
that.

In part, I hop this (and hopefully the related implementation note) will 
be useful in discussing different ways in which Swift can manage data. 
>From a SwiftScript perspective, the below note should document what I 
think needs to be provided by any modified implementation.

Discussion welcome.


How an app procedure call maps into an application executable call, from a 
Swift user perspective, attempting to avoid the mechanics inside Swift. 
===========

In some of these notes, there is reference to this example Swift 
program:

 type file;

 app (file o) count(file i) {
   wc @i stdout=@o;
 }

 file q <"input.txt">;
 file r <"output.txt">;

The executable for wc will be looked up in tc.data.

This unix executable will then be executed in some //application procedure 
workspace//. This means:

Each application procedure workspace will have an application workspace 
directory.  (TODO: can collapse terms //application procedure workspace// 
and //application workspace directory// ?

This application workspace directory will not be shared with any other 
//application procedure execution attempt//; all application procedure 
execution attempts will run with distinct application procedure 
workspaces. (for the avoidance of doubt:

 If a //SwiftScript procedure invocation// is subject to multiple 
 application procedure execution attempts (due to Swift-level restarts, 
 retries or replication) then each of those application rocedure execution 
 attempts will be made in a different application procedure workspace.
)

The application workspace directory will be a directory on a POSIX 
filesystem accessible throughout the application execution by the 
application executable.

Before the //application executable// is executed:

* The application workspace directory will exist.

* The //input files// will exist inside the application workspace 
directory (but not necessarily as direct children; there may be 
subdirectories within the application workspace directory).

* The //input files// will be those files //mapped// to //input 
parameters// of the application procedure invocation. (In the example, 
this means that the file input.txt will exist in the application workspace 
directory)

* For each input file dataset, it will be the case that @filename or 
@filenames invoked with that dataset as a parameter will return the path 
relative to the application workspace directory for the file(s) that are 
associated with that dataset. (In the example, that means that @i will 
evaluate to the path "input.txt")

* For each //file-bound// parameter of the Swift procedure invocation, the 
associated files (determined by data type?) will always exist.

* The input files must be treated as read only files. This may or may not 
be enforced by unix file system permissions.

During/after the //application executable execution//, the following must 
be true:

* If the application executable execution was successful (in the opinion 
of the application executable), then the application executable should 
exit with //unix return code// 0; if the application executable execution 
was unsuccessful (in the opinion of the application executable), then the 
application executable should exit with //unix return code// not equal to 
0.

* Each file mapped from an output parameter of the SwiftScript procedure 
call must exist. Files will be mapped in the same way as for input files.

(? Is it defined that output subdirectories will be precreated before 
execution or should app executables expect to make them? That's probably 
determined by the present behaviour of wrapper.sh)

Things to not assume:

* anything about the path of the application workspace directory

* that either the application workspace directory will be deleted or will 
continue to exist or will remain unmodified after execution has finished

* that files can be passed(?def) between application procedure invocations 
through any mechanism except through files known to Swift through the 
mapping mechanism (there is some exception here for extern datasets - 
there are a separate set of assertions that hold for extern datasets)

--