Debian Codegraph @

pario/doc/sf.html

raw
1 <HTML>
2 <HEAD>
3 <META NAME="GENERATOR" CONTENT="Adobe PageMill 3.0 Win">
4 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
5 <META NAME="Author" CONTENT="Magdalena Nieplocha">
6 <TITLE>sf gowno</TITLE>
7 </HEAD>
8 <BODY BGCOLOR="#f8f8eb" LINK="#0000ee" VLINK="#990099" TEXT="#000099"
9 ALINK="#00ffff" BACKGROUND="Image2.gif">
10
11 <H2><CENTER><A NAME="overview"></A></CENTER></H2>
12
13 <H2><CENTER>Shared Files Library</CENTER></H2>
14
15 <P>The Shared Files (SF) library implements logically-shared temporary
16 files for parallel SPMD (single-program-multiple-data) applications.
17 Any process can read and write at arbitrary location in a file
18 independently of other processes. Shared files must be created
19 and destroyed collectively. To optimize performance of the library,
20 user can provide hints on:</P>
21
22 <UL>
23 <LI>soft limit, and
24 <LI>hard limit for the file size.
25 </UL>
26
27 <P>The SF <I>read </I>and <I>write</I> operations are asynchronous/nonblocking
28 and require a <I>wait</I> operation to complete.</P>
29
30 <P>Due to the FORTRAN data type limitations, in order to facilitate
31 access to files &gt;2GB the file size, request size and offset
32 arguments use double precision data types.</P>
33
34 <P>All SF routines return an error code. The &quot;0&quot; value
35 means success, other values correspond to error codes.</P>
36
37 <P><HR ALIGN=LEFT></P>
38
39 <H2><A NAME="sf_create"></A></H2>
40
41 <H2>sf_create</H2>
42
43 <PRE>integer sf_create(fname, size_hard_limit, size_soft_limit, req_size, handle)
44 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; fname&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- meta-file name
45 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; size_hard_limit&nbsp; -- max file size in bytes not to be exceeded (a hint)
46 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; size_soft_limit&nbsp; -- estimated file size (a hint)
47 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; req_size&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- size of&nbsp; a typical request (a hint)
48 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; handle&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- returned handle to the created file</PRE>
49
50 <P>Creates shared file using name and path specified in <I>fname
51 </I>as a template. <BR>
52 <I>req_size</I> specifies size of a typical request (-1. means
53 &quot;don't know&quot;).</P>
54
55 <P>Creates shared file using name and path specified in fname
56 as a template. <BR>
57 req_size specifies size of a typical request (-1. means &quot;don't
58 know&quot;).</P>
59
60 <P>It is a collective operation.</P>
61
62 <P><HR ALIGN=LEFT></P>
63
64 <P><A NAME="sf_write"></A></P>
65
66 <H2>sf_write</H2>
67
68 <P>&nbsp;</P>
69
70 <PRE>integer sf_write(handle, offset, bytes, buffer, request_id)
71 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; handle&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- file handle returned from sf_create&nbsp;&nbsp; [in]
72 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; offset&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- location in file (from the beginning)
73 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; where data should be written to&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [in]
74 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; buffer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- local array to put the data&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [in]
75 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bytes&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- number of bytes to read&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [in]
76 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; request_id&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- id identifying asynchronous operation [out]</PRE>
77
78 <P>Asynchronous write operation. Writes number of <I>bytes</I>
79 to the file identified by <I>handle</I> at location <I>offset</I>.Operation
80 is guaranteed to be complete when <I>sf_wait</I> called with <I>request_id
81 </I>argument returns. <BR>
82 <HR ALIGN=LEFT></P>
83
84 <H2><A NAME="sf_read"></A></H2>
85
86 <H2>sf_read</H2>
87
88 <PRE>integer sf_read(handle, offset, bytes, buffer, request_id)
89 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; handle&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- file handle returned from sf_create&nbsp;&nbsp; [in]
90 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; offset&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- location in file (from the beginning)
91 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; where data should be read from&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [in]
92 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; buffer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- local array to put the data&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [in]
93 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bytes&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- number of bytes to read&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [in]
94 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; request_id&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- id identifying asynchronous operation [out]</PRE>
95
96 <P>Asynchronous read operation. Reads number of <I>bytes</I> to
97 the file identified by <I>handle</I> at location <I>offset</I>.Operation
98 is guaranteed to be complete when <I>sf_wait</I> called with <I>request_id
99 </I>argument returns.</P>
100
101 <P><HR ALIGN=LEFT></P>
102
103 <H2><A NAME="sf_wait"></A></H2>
104
105 <H2>sf_wait</H2>
106
107 <PRE>integer sf_wait(request_id)
108 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; request_id&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- id identifying asynchronous operation [in/out]</PRE>
109
110 <P>Blocks the calling process until I/O operation associated with
111 <I>request</I>_<I>id</I> completes. <BR>
112 Invalidates <I>request_id.</I> <BR>
113 &nbsp;<BR>
114 &nbsp;<HR ALIGN=LEFT><BR>
115 <A NAME="sf_waitall"></A></P>
116
117 <H2>sf_waitall</H2>
118
119 <PRE>integer sf_waitall(list, num)
120 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; list(num)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- array of ids for asynchronous operations [in/out]
121 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; num&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- number of entries in list&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [in]</PRE>
122
123 <P>Blocks the calling process until all of the <I>num</I> I/O
124 operations associated with <I>ids</I><BR>
125 specified in <I>list</I> complete. Invalidates (modifies) <I>ids</I>
126 on the <I>list.</I><BR>
127 <HR ALIGN=LEFT></P>
128
129 <H2><A NAME="sf_destroy"></A></H2>
130
131 <H2>sf_destroy</H2>
132
133 <PRE>
134 integer sf_destroy(handle)
135 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; handle&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -- file handle returned from sf_create&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [in]</PRE>
136
137 <P>Destroys the shared file associated with <I>handle</I>. It
138 is a collective operation.
139
140 </BODY>
141 </HTML>