/usr/share/gap/pkg/scscp/doc/chap3.html is in gap-scscp 2.1.4+ds-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (scscp) - Chapter 3: Using streams</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap3" onload="jscontent()">
<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chap8.html">8</a> <a href="chap9.html">9</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap2.html">[Previous Chapter]</a> <a href="chap4.html">[Next Chapter]</a> </div>
<p><a id="X7CB06121820FD0DD" name="X7CB06121820FD0DD"></a></p>
<div class="ChapSects"><a href="chap3.html#X7CB06121820FD0DD">3 <span class="Heading">Using streams</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X79EB93A27D9AC115">3.1 <span class="Heading">Input-output TCP streams</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X805BB9468642A787">3.1-1 IsInputOutputTCPStream</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X817A945B83659813">3.1-2 IsInputOutputTCPStreamRep</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7E3D43CF7B049F04">3.1-3 InputOutputTCPStream</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X86CA5D6C79B32600">3.2 <span class="Heading">Example of client-server communication via input-output TCP streams</span></a>
</span>
</div>
</div>
<h3>3 <span class="Heading">Using streams</span></h3>
<p>The package implements new kind of <strong class="pkg">GAP</strong> input-output streams, called input-output TCP streams. Such streams are based on the functionality for the TCP/IP protocol usage provided by the <strong class="pkg">GAP</strong> package <strong class="pkg">IO</strong>, and may constitute an independent interest for <strong class="pkg">GAP</strong> users.</p>
<p>Input-output TCP streams are intended to support all operations, implemented for streams in <strong class="pkg">GAP</strong>. It is assumed that all existing code using streams should work with this kind of streams as well (please let us know, if you will notice that this is not the case!). We installed methods for input-output TCP streams to support the following operations: <code class="func">ViewObj</code> (<span class="RefLink">Reference: ViewObj</span>), <code class="func">PrintObj</code> (<span class="RefLink">Reference: PrintObj</span>), <code class="func">ReadByte</code> (<span class="RefLink">Reference: ReadByte</span>), <code class="func">ReadLine</code> (<span class="RefLink">Reference: ReadLine</span>), <code class="func">ReadAll</code> (<span class="RefLink">Reference: ReadAll</span>), <code class="func">WriteByte</code> (<span class="RefLink">Reference: WriteByte</span>), <code class="func">WriteLine</code> (<span class="RefLink">Reference: WriteLine</span>), <code class="func">WriteAll</code> (<span class="RefLink">Reference: WriteAll</span>), <code class="func">IsEndOfStream</code> (<span class="RefLink">Reference: IsEndOfStream</span>), <code class="func">CloseStream</code> (<span class="RefLink">Reference: CloseStream</span>), <code class="func">FileDescriptorOfStream</code> (<span class="RefLink">Reference: FileDescriptorOfStream</span>), <code class="func">UNIXSelect</code> (<span class="RefLink">Reference: UNIXSelect</span>).</p>
<p><a id="X79EB93A27D9AC115" name="X79EB93A27D9AC115"></a></p>
<h4>3.1 <span class="Heading">Input-output TCP streams</span></h4>
<p><a id="X805BB9468642A787" name="X805BB9468642A787"></a></p>
<h5>3.1-1 IsInputOutputTCPStream</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ IsInputOutputTCPStream</code></td><td class="tdright">( filter )</td></tr></table></div>
<p><code class="func">IsInputOutputTCPStream</code> is a subcategory of <code class="func">IsInputOutputStream</code> (<span class="RefLink">Reference: IsInputOutputStream</span>). Streams in the category <code class="func">IsInputOutputTCPStream</code> are created with the help of the function <code class="func">InputOutputTCPStream</code> (<a href="chap3.html#X7E3D43CF7B049F04"><span class="RefLink">3.1-3</span></a>) with one or two arguments dependently on whether they will be used in the client or server mode. Examples of their creation and usage will be given in subsequent sections.</p>
<p><a id="X817A945B83659813" name="X817A945B83659813"></a></p>
<h5>3.1-2 IsInputOutputTCPStreamRep</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ IsInputOutputTCPStreamRep</code></td><td class="tdright">( filter )</td></tr></table></div>
<p>This is the representation used for streams in the category <code class="func">IsInputOutputTCPStream</code> (<a href="chap3.html#X805BB9468642A787"><span class="RefLink">3.1-1</span></a>).</p>
<p><a id="X7E3D43CF7B049F04" name="X7E3D43CF7B049F04"></a></p>
<h5>3.1-3 InputOutputTCPStream</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InputOutputTCPStream</code>( <var class="Arg">desc</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InputOutputTCPStream</code>( <var class="Arg">host</var>, <var class="Arg">port</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: stream</p>
<p>The one-argument version must be called from the <strong class="pkg">SCSCP</strong> server. Its argument <var class="Arg">desc</var> must be a socket descriptor obtained using <code class="func">IO_accept</code> (<a href="/usr/share/gap/pkg/io/doc/chap3.html#X7E474E9787012FE4"><span class="RefLink">IO: IO_accept</span></a>) function from the <strong class="pkg">IO</strong> package (see the example below). It returns a stream in the category <code class="func">IsInputOutputTCPStream</code> (<a href="chap3.html#X805BB9468642A787"><span class="RefLink">3.1-1</span></a>) which will use this socket to accept incoming connections. In most cases, the one-argument version is called automatically from <code class="func">RunSCSCPserver</code> (<a href="chap5.html#X831C84577884215E"><span class="RefLink">5.2-1</span></a>) rather then manually.</p>
<p>The version with two arguments, a string <var class="Arg">host</var> and an integer <var class="Arg">port</var>, must be called from the <strong class="pkg">SCSCP</strong> client. It returns a stream in the category <code class="func">IsInputOutputTCPStream</code> (<a href="chap3.html#X805BB9468642A787"><span class="RefLink">3.1-1</span></a>) which will be used by the client for communication with the <strong class="pkg">SCSCP</strong> server running at hostname <var class="Arg">host</var> on port <var class="Arg">port</var>. In most cases, the two-argument version is called automatically from the higher level functions, for example, <code class="func">EvaluateBySCSCP</code> (<a href="chap6.html#X7C745B2878E0AC41"><span class="RefLink">6.3-1</span></a>).</p>
<p><a id="X86CA5D6C79B32600" name="X86CA5D6C79B32600"></a></p>
<h4>3.2 <span class="Heading">Example of client-server communication via input-output TCP streams</span></h4>
<p>The following example demonstrates the low-level interaction between client and server using input-output TCP stream, and shows how such streams are created in the function <code class="func">RunSCSCPserver</code> (<a href="chap5.html#X831C84577884215E"><span class="RefLink">5.2-1</span></a>). It uses some functions from the <strong class="pkg">IO</strong> package (see the <strong class="pkg">IO</strong> manual for their description). We will show step by step what is happens on server and client (of course, if you will try this example, the numbers denoting descriptors may be different).</p>
<p>Firts, we will start two <strong class="pkg">GAP</strong> sessions, one for the server, another one for the client. Now we enter the following commands on the server's side:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">sock := IO_socket( IO.PF_INET, IO.SOCK_STREAM, "tcp" );</span>
3
<span class="GAPprompt">gap></span> <span class="GAPinput">lookup := IO_gethostbyname( "localhost" );</span>
rec( name := "localhost", aliases := [ ], addrtype := 2, length := 4,
addr := [ "\177\000\000\>" ] )
<span class="GAPprompt">gap></span> <span class="GAPinput">port:=26133;</span>
26133
<span class="GAPprompt">gap></span> <span class="GAPinput">res := IO_bind( sock, IO_make_sockaddr_in( lookup.addr[1], port ) );</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">IO_listen( sock, 5 );</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">socket_descriptor := IO_accept( sock, IO_MakeIPAddressPort("0.0.0.0",0) );</span>
</pre></div>
<p>After the last command you will not see the <strong class="pkg">GAP</strong> prompt because the server starts to wait for an incoming connection. Now we go to the client's side and create an input-output TCP stream to the server. Here it can be created in one step:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">clientstream:=InputOutputTCPStream( "localhost", 26133 );</span>
Creating a socket...
Connecting to a remote socket via TCP/IP...
</pre></div>
<p>Now we are trying to connect to the server, and as soon as the connection will be established, the stream will be created at the client side, and we will see the output and the new <strong class="pkg">GAP</strong> prompt:</p>
<div class="example"><pre>
< input/output TCP stream to localhost >
gap>
</pre></div>
<p>On the server you will get the socket descriptor and then you will be able to create a stream from it:</p>
<div class="example"><pre>
4
<span class="GAPprompt">gap></span> <span class="GAPinput">serverstream := InputOutputTCPStream( socket_descriptor );</span>
< input/output TCP stream to socket >
</pre></div>
<p>Now we can write to this stream on the client side and then read from it on the server side and backwards. First, write on the client:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">WriteLine( clientstream, "12345" );</span>
true
</pre></div>
<p>Now read and write on the server:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ReadLine( serverstream );</span>
"12345\n"
<span class="GAPprompt">gap></span> <span class="GAPinput">WriteLine( serverstream, "54321" );</span>
true
</pre></div>
<p>And finally we read on the client and close the stream:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ReadLine( clientstream );</span>
"54321\n"
<span class="GAPprompt">gap></span> <span class="GAPinput">CloseStream( clientstream );</span>
</pre></div>
<p>and similarly close the stream on the server:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">CloseStream( serverstream );</span>
</pre></div>
<p>In this way one can organise remote communication between two copies of <strong class="pkg">GAP</strong> in various ways. In subsequent chapters we explain how it is implemented using <strong class="pkg">SCSCP</strong> to ensure compatibility not only with <strong class="pkg">GAP</strong> but with any other <strong class="pkg">SCSCP</strong>-compliant system.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap2.html">[Previous Chapter]</a> <a href="chap4.html">[Next Chapter]</a> </div>
<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chap8.html">8</a> <a href="chap9.html">9</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
|