design.txt - clic - Clic is an command line interactive client for gopher writt… | |
git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65… | |
Log | |
Files | |
Refs | |
Tags | |
README | |
LICENSE | |
--- | |
design.txt (3830B) | |
--- | |
1 | |
2 -*- text -*- | |
3 | |
4 $Id$ | |
5 | |
6 | |
7 usocket: Universal sockets library | |
8 ================================== | |
9 | |
10 Contents | |
11 ======== | |
12 | |
13 * Motivation | |
14 * Design goal | |
15 * Functional requirements | |
16 * Class structure | |
17 | |
18 | |
19 | |
20 Motivation | |
21 ========== | |
22 | |
23 There are 2 other portability sockets packages [that I know of] | |
24 out there: | |
25 | |
26 1) trivial-sockets | |
27 2) acl-compat (which is a *lot* broader, but contains sockets too) | |
28 | |
29 The first misses some functionality which is fundamental when | |
30 the requirements stop being 'trivial', such as finding out the | |
31 addresses of either side connected to the tcp/ip stream. | |
32 | |
33 The second, being a complete compatibility library for Allegro, | |
34 contains much more than only sockets. Next to that, as the docs | |
35 say, is it mainly directed at providing the functionality required | |
36 to port portable-allegroserve - meaning it may be (very) incomplete | |
37 on some platforms. | |
38 | |
39 So, that's why I decided to inherit Erik Enge's project to build | |
40 a library with the intention to provide portability code in only | |
41 1 area of programming, targeted at 'not so trivial' programming. | |
42 | |
43 Also, I need this library to extend cl-irc with full DCC functionality. | |
44 | |
45 | |
46 | |
47 Design goal | |
48 =========== | |
49 | |
50 To provide a portable TCP/IP socket interface for as many | |
51 implementations as possible, while keeping the portability layer | |
52 as thin as possible. | |
53 | |
54 | |
55 | |
56 Functional requirements | |
57 ======================= | |
58 | |
59 The interface provided should allow: | |
60 - 'client'/active sockets | |
61 - 'server'/listening sockets | |
62 - provide the usual stream methods to operate on the connection stream | |
63 (not necessarily the socket itself; maybe a socket slot too) | |
64 | |
65 For now, as long as there are no possibilities to have UDP sockets | |
66 to write a DNS client library: (which in the end may work better, | |
67 because in this respect all implementations are different...) | |
68 - retrieve IP addresses/ports for both sides of the connection | |
69 | |
70 Several relevant support functionalities will have to be provided too: | |
71 - long <-> quad-vector operators | |
72 - quad-vector <-> string operators | |
73 - hostname <-> quad-vector operators (hostname resolution) | |
74 | |
75 | |
76 Minimally, I'd like to support: | |
77 - SBCL | |
78 - CMUCL | |
79 - ABCL (ArmedBear) | |
80 - clisp | |
81 - Allegro | |
82 - LispWorks | |
83 - OpenMCL | |
84 | |
85 | |
86 Comments on the design above | |
87 ============================ | |
88 | |
89 I don't think it's a good idea to implement name lookup in the | |
90 very first of steps: we'll see if this is required to get the | |
91 package accepted; not all implementations support it. | |
92 | |
93 Name resolution errors ... | |
94 Since there is no name resolution library (yet), nor standardized | |
95 hooks into the standard C library to do it the same way on | |
96 all platforms, name resolution errors can manifest themselves | |
97 in a lot of different ways. How to marshall these to the | |
98 library users? | |
99 | |
100 Several solutions come to mind: | |
101 | |
102 1) Map them to 'unknown-error | |
103 2) Give them their own errors and map to those | |
104 ... which implies that they are actually supported atm. | |
105 3) ... | |
106 | |
107 Given that the library doesn't now, but may in the future, | |
108 include name resolution officially, I tend to think (1) is the | |
109 right answer: it leaves it all undecided. | |
110 | |
111 These errors can be raised by the nameresolution service | |
112 (netdb.h) as values for 'int h_errno': | |
113 | |
114 - HOST_NOT_FOUND (1) | |
115 - TRY_AGAIN (2) /* Server fail or non-authoritive Host not found */ | |
116 - NO_RECOVERY (3) /* Failed permanently */ | |
117 - NO_DATA (4) /* Valid address, no data for requested record */ | |
118 | |
119 int *__h_errno_location(void) points to thread local h_errno on | |
120 threaded glibc2 systems. | |
121 | |
122 | |
123 Class structure | |
124 =============== | |
125 | |
126 usocket | |
127 | | |
128 +- datagram-usocket | |
129 +- stream-usocket | |
130 \- stream-server-usocket | |
131 | |
132 The usocket class will have methods to query local properties, such | |
133 as: | |
134 | |
135 - get-local-name: to query to which interface the socket is bound | |
136 - <other socket and protocol options such as SO_REUSEADDRESS> |