design.txt - clic - Clic is an command line interactive client for gopher written in Common LISP
(HTM) git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/clic/
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Tags
(DIR) README
(DIR) 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>