Mercurial > luasocket

comparison doc/introduction.html @ 0:4b915342e2a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaSocket 2.0.2 + CMake build description.
author Eric Wing <ewing . public |-at-| gmail . com>
date Tue, 26 Aug 2008 18:40:01 -0700
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4b915342e2a8
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3 <html>
4
5 <head>
6 <meta name="description" content="LuaSocket: Introduction to the core">
7 <meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network,
8 Library, Support">
9 <title>LuaSocket: Introduction to the core</title>
10 <link rel="stylesheet" href="reference.css" type="text/css">
11 </head>
12
13 <body>
14
15 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17 <div class=header>
18 <hr>
19 <center>
20 <table summary="LuaSocket logo">
21 <tr><td align=center><a href="http://www.lua.org">
22 <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23 </a></td></tr>
24 <tr><td align=center valign=top>Network support for the Lua language
25 </td></tr>
26 </table>
27 <p class=bar>
28 <a href="home.html">home</a> &middot;
29 <a href="home.html#download">download</a> &middot;
30 <a href="installation.html">installation</a> &middot;
31 <a href="introduction.html">introduction</a> &middot;
32 <a href="reference.html">reference</a>
33 </p>
34 </center>
35 <hr>
36 </div>
37
38 <!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40 <h2>Introduction</h2>
41
42 <p>
43 LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
44 that is composed by two parts: a C core that provides support for the TCP
45 and UDP transport layers, and a set of Lua modules that add support for
46 the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and
47 downloading files) protocols and other functionality commonly needed by
48 applications that deal with the Internet. This introduction is about the C
49 core.
50 </p>
51
52 <p>
53 Communication in LuaSocket is performed via I/O objects. These can
54 represent different network domains. Currently, support is provided for TCP
55 and UDP, but nothing prevents other developers from implementing SSL, Local
56 Domain, Pipes, File Descriptors etc. I/O objects provide a standard
57 interface to I/O across different domains and operating systems.
58 </p>
59
60 <p>
61 The API design had two goals in mind. First, users
62 experienced with the C API to sockets should feel comfortable using LuaSocket.
63 Second, the simplicity and the feel of the Lua language should be
64 preserved. To achieve these goals, the LuaSocket API keeps the function names and semantics the C API whenever possible, but their usage in Lua has been greatly simplified.
65 </p>
66
67
68 <p>
69 One of the simplifications is the receive pattern capability.
70 Applications can read data from stream domains (such as TCP)
71 line by line, block by block, or until the connection is closed.
72 All I/O reads are buffered and the performance differences between
73 different receive patterns are negligible.
74 </p>
75
76 <p>
77 Another advantage is the flexible timeout control
78 mechanism. As in C, all I/O operations are blocking by default. For
79 example, the <a href=tcp.html#send><tt>send</tt></a>,
80 <a href=tcp.html#receive><tt>receive</tt></a> and
81 <a href=tcp.html#accept><tt>accept</tt></a> methods
82 of the TCP domain will block the caller application until
83 the operation is completed (if ever!). However, with a call to the
84 <a href=tcp.html#settimeout><tt>settimeout</tt></a>
85 method, an application can specify upper limits on
86 the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on
87 the time LuaSocket can internally be blocked by any OS call (the
88 "<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket
89 call might perform several OS calls, so that the two timeout values are
90 <em>not</em> equivalent.
91 </p>
92
93 <p>
94 Finally, the host name resolution is transparent, meaning that most
95 functions and methods accept both IP addresses and host names. In case a
96 host name is given, the library queries the system's resolver and
97 tries the main IP address returned. Note that direct use of IP addresses
98 is more efficient, of course. The
99 <a href=dns.html#toip><tt>toip</tt></a>
100 and <a href=dns.html#tohostname><tt>tohostname</tt></a>
101 functions from the DNS module are provided to convert between host names and IP addresses.
102 </p>
103
104 <p>
105 Together, these changes make network programming in LuaSocket much simpler
106 than it is in C, as the following sections will show.
107 </p>
108
109 <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110
111 <h3 id=tcp>TCP</h3>
112
113 <p>
114 TCP (Transfer Control Protocol) is reliable stream protocol. In other
115 words, applications communicating through TCP can send and receive data as
116 an error free stream of bytes. Data is split in one end and
117 reassembled transparently on the other end. There are no boundaries in
118 the data transfers. The library allows users to read data from the
119 sockets in several different granularities: patterns are available for
120 lines, arbitrary sized blocks or "read up to connection closed", all with
121 good performance.
122 </p>
123
124 <p>
125 The library distinguishes three types of TCP sockets: <em>master</em>,
126 <em>client</em> and <em>server</em> sockets.
127 </p>
128
129 <p>
130 Master sockets are newly created TCP sockets returned by the function
131 <a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is
132 transformed into a server socket
133 after it is associated with a <em>local</em> address by a call to the
134 <a href=tcp.html#bind><tt>bind</tt></a> method followed by a call to the
135 <a href=tcp.html#listen><tt>listen</tt></a>. Conversely, a master socket
136 can be changed into a client socket with the method
137 <a href=tcp.html#connect><tt>connect</tt></a>,
138 which associates it with a <em>remote</em> address.
139 </p>
140
141 <p>
142 On server sockets, applications can use the
143 <a href=tcp.html#accept><tt>accept</tt></a> method
144 to wait for a client connection. Once a connection is established, a
145 client socket object is returned representing this connection. The
146 other methods available for server socket objects are
147 <a href=tcp.html#getsockname><tt>getsockname</tt></a>,
148 <a href=tcp.html#setoption><tt>setoption</tt></a>,
149 <a href=tcp.html#settimeout><tt>settimeout</tt></a>, and
150 <a href=tcp.html#close><tt>close</tt></a>.
151 </p>
152
153 <p>
154 Client sockets are used to exchange data between two applications over
155 the Internet. Applications can call the methods
156 <a href=tcp.html#send><tt>send</tt></a> and
157 <a href=tcp.html#receive><tt>receive</tt></a>
158 to send and receive data. The other methods
159 available for client socket objects are
160 <a href=tcp.html#getsockname><tt>getsockname</tt></a>,
161 <a href=tcp.html#getpeername><tt>getpeername</tt></a>,
162 <a href=tcp.html#setoption><tt>setoption</tt></a>,
163 <a href=tcp.html#settimeout><tt>settimeout</tt></a>,
164 <a href=tcp.html#shutdown><tt>shutdown</tt></a>, and
165 <a href=tcp.html#close><tt>close</tt></a>.
166 </p>
167
168 <p>
169 Example:
170 </p>
171 <blockquote>
172 <p>
173 A simple echo server, using LuaSocket. The program binds to an ephemeral
174 port (one that is chosen by the operating system) on the local host and
175 awaits client connections on that port. When a connection is established,
176 the program reads a line from the remote end and sends it back, closing
177 the connection immediately. You can test it using the telnet
178 program.
179 </p>
180
181 <pre class=example>
182 -- load namespace
183 local socket = require("socket")
184 -- create a TCP socket and bind it to the local host, at any port
185 local server = assert(socket.bind("*", 0))
186 -- find out which port the OS chose for us
187 local ip, port = server:getsockname()
188 -- print a message informing what's up
189 print("Please telnet to localhost on port " .. port)
190 print("After connecting, you have 10s to enter a line to be echoed")
191 -- loop forever waiting for clients
192 while 1 do
193 -- wait for a connection from any client
194 local client = server:accept()
195 -- make sure we don't block waiting for this client's line
196 client:settimeout(10)
197 -- receive the line
198 local line, err = client:receive()
199 -- if there was no error, send it back to the client
200 if not err then client:send(line .. "\n") end
201 -- done with client, close the object
202 client:close()
203 end
204 </pre>
205 </blockquote>
206
207 <!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
208
209 <h3 id=udp>UDP</h3>
210
211 <p>
212 UDP (User Datagram Protocol) is a non-reliable datagram protocol. In
213 other words, applications communicating through UDP send and receive
214 data as independent blocks, which are not guaranteed to reach the other
215 end. Even when they do reach the other end, they are not guaranteed to be
216 error free. Data transfers are atomic, one datagram at a time. Reading
217 only part of a datagram discards the rest, so that the following read
218 operation will act on the next datagram. The advantages are in
219 simplicity (no connection setup) and performance (no error checking or
220 error correction).
221 </p>
222
223 <p>
224 Note that although no guarantees are made, these days
225 networks are so good that, under normal circumstances, few errors
226 happen in practice.
227 </p>
228
229 <p>
230 An UDP socket object is created by the
231 <a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP
232 sockets do not need to be connected before use. The method
233 <a href=udp.html#sendto><tt>sendto</tt></a>
234 can be used immediately after creation to
235 send a datagram to IP address and port. Host names are not allowed
236 because performing name resolution for each packet would be forbiddingly
237 slow. Methods
238 <a href=udp.html#receive><tt>receive</tt></a> and
239 <a href=udp.html#receivefrom><tt>receivefrom</tt></a>
240 can be used to retrieve datagrams, the latter returning the IP and port of
241 the sender as extra return values (thus being slightly less
242 efficient).
243 </p>
244
245 <p>
246 When communication is performed repeatedly with a single peer, an
247 application should call the
248 <a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a
249 permanent partner. Methods
250 <a href=udp.html#sendto><tt>sendto</tt></a> and
251 <a href=udp.html#receivefrom><tt>receivefrom</tt></a>
252 can no longer be used, but the method
253 <a href=udp.html#send><tt>send</tt></a> can be used to send data
254 directly to the peer, and the method
255 <a href=udp.html#receive><tt>receive</tt></a>
256 will only return datagrams originating
257 from that peer. There is about 30% performance gain due to this practice.
258 </p>
259
260 <p>
261 To associate an UDP socket with a local address, an application calls the
262 <a href=udp.html#setsockname><tt>setsockname</tt></a>
263 method <em>before</em> sending any datagrams. Otherwise, the socket is
264 automatically bound to an ephemeral address before the first data
265 transmission and once bound the local address cannot be changed.
266 The other methods available for UDP sockets are
267 <a href=udp.html#getpeername><tt>getpeername</tt></a>,
268 <a href=udp.html#getsockname><tt>getsockname</tt></a>,
269 <a href=udp.html#settimeout><tt>settimeout</tt></a>,
270 <a href=udp.html#setoption><tt>setoption</tt></a> and
271 <a href=udp.html#close><tt>close</tt></a>.
272 </p>
273
274 <p>
275 Example:
276 </p>
277 <blockquote>
278 <p>
279 A simple daytime client, using LuaSocket. The program connects to a remote
280 server and tries to retrieve the daytime, printing the answer it got or an
281 error message.
282 </p>
283
284 <pre class=example>
285 -- change here to the host an port you want to contact
286 local host, port = "localhost", 13
287 -- load namespace
288 local socket = require("socket")
289 -- convert host name to ip address
290 local ip = assert(socket.dns.toip(host))
291 -- create a new UDP object
292 local udp = assert(socket.udp())
293 -- contact daytime host
294 assert(udp:sendto("anything", ip, port))
295 -- retrieve the answer and print results
296 io.write(assert(udp:receive()))
297 </pre>
298 </blockquote>
299
300 <!-- More +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
301
302 <h3 id=more>Support modules</h3>
303
304 <p> Although not covered in the introduction, LuaSocket offers
305 much more than TCP and UDP functionality. As the library
306 evolved, support for <a href=http.html>HTTP</a>, <a href=ftp.html>FTP</a>,
307 and <a href=smtp.html>SMTP</a> were built on top of these. These modules
308 and many others are covered by the <a href=reference.html>reference manual</a>.
309 </p>
310
311 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
312
313 <div class=footer>
314 <hr>
315 <center>
316 <p class=bar>
317 <a href="home.html">home</a> &middot;
318 <a href="home.html#down">download</a> &middot;
319 <a href="installation.html">installation</a> &middot;
320 <a href="introduction.html">introduction</a> &middot;
321 <a href="reference.html">reference</a>
322 </p>
323 <p>
324 <small>
325 Last modified by Diego Nehab on <br>
326 Thu Apr 20 00:25:36 EDT 2006
327 </small>
328 </p>
329 </center>
330 </div>
331
332 </body>
333 </html>