Mercurial > projects > ldc

comparison tango/tango/io/protocol/model/IReader.d @ 132:1700239cab2e trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[svn r136] MAJOR UNSTABLE UPDATE!!! Initial commit after moving to Tango instead of Phobos. Lots of bugfixes... This build is not suitable for most things.
author lindquist
date Fri, 11 Jan 2008 17:57:40 +0100
parents
children
comparison
equal deleted inserted replaced
131:5825d48b27d1 132:1700239cab2e
1 /*******************************************************************************
2
3 copyright: Copyright (c) 2004 Kris Bell. All rights reserved
4
5 license: BSD style: $(LICENSE)
6
7 version: Oct 2004: Initial release
8 Dec 2006: Outback release
9
10 author: Kris
11 Ivan Senji (the "alias get" idea)
12
13 *******************************************************************************/
14
15 module tango.io.protocol.model.IReader;
16
17 public import tango.io.model.IBuffer;
18
19 private import tango.io.protocol.model.IProtocol;
20
21 /*******************************************************************************
22
23 IReader interface. Each reader operates upon an IBuffer, which is
24 provided at construction time. Readers are simple converters of data,
25 and have reasonably rigid rules regarding data format. For example,
26 each request for data expects the content to be available; an exception
27 is thrown where this is not the case. If the data is arranged in a more
28 relaxed fashion, consider using IBuffer directly instead.
29
30 All readers support the full set of native data types, plus a full
31 selection of array types. The latter can be configured to produce
32 either a copy (.dup) of the buffer content, or a slice. See classes
33 HeapCopy, BufferSlice and HeapSlice for more on this topic. Applications
34 can disable memory management by configuring a Reader with one of the
35 binary oriented protocols, and ensuring the optional protocol 'prefix'
36 is disabled.
37
38 Readers support Java-esque get() notation. However, the Tango
39 style is to place IO elements within their own parenthesis, like
40 so:
41
42 ---
43 int count;
44 char[] verse;
45
46 read (verse) (count);
47 ---
48
49 Note that each element read is distict; this style is affectionately
50 known as "whisper". The code below illustrates basic operation upon a
51 memory buffer:
52
53 ---
54 auto buf = new Buffer (256);
55
56 // map same buffer into both reader and writer
57 auto read = new Reader (buf);
58 auto write = new Writer (buf);
59
60 int i = 10;
61 long j = 20;
62 double d = 3.14159;
63 char[] c = "fred";
64
65 // write data using whisper syntax
66 write (c) (i) (j) (d);
67
68 // read them back again
69 read (c) (i) (j) (d);
70
71
72 // same thing again, but using put() syntax instead
73 write.put(c).put(i).put(j).put(d);
74 read.get(c).get(i).get(j).get(d);
75 ---
76
77 Note that certain protocols, such as the basic binary implementation,
78 expect to retrieve the number of array elements from the source. For
79 example: when reading an array from a file, the number of elements
80 is read from the file also, and the configurable memory-manager is
81 invoked to provide the array space. If content is not arranged in
82 such a manner you may read array content directly either by creating
83 a Reader with a protocol configured to sidestep array-prefixing, or
84 by accessing buffer content directly (via the methods exposed there)
85 e.g.
86
87 ---
88 void[10] data;
89
90 reader.buffer.fill (data);
91 ---
92
93 Readers may also be used with any class implementing the IReadable
94 interface, along with any struct implementing an equivalent method
95
96 *******************************************************************************/
97
98 abstract class IReader // could be an interface, but that causes poor codegen
99 {
100 alias get opCall;
101
102 /***********************************************************************
103
104 These are the basic reader methods
105
106 ***********************************************************************/
107
108 abstract IReader get (inout bool x);
109 abstract IReader get (inout byte x); /// ditto
110 abstract IReader get (inout ubyte x); /// ditto
111 abstract IReader get (inout short x); /// ditto
112 abstract IReader get (inout ushort x); /// ditto
113 abstract IReader get (inout int x); /// ditto
114 abstract IReader get (inout uint x); /// ditto
115 abstract IReader get (inout long x); /// ditto
116 abstract IReader get (inout ulong x); /// ditto
117 abstract IReader get (inout float x); /// ditto
118 abstract IReader get (inout double x); /// ditto
119 abstract IReader get (inout real x); /// ditto
120 abstract IReader get (inout char x); /// ditto
121 abstract IReader get (inout wchar x); /// ditto
122 abstract IReader get (inout dchar x); /// ditto
123
124 abstract IReader get (inout bool[] x); /// ditto
125 abstract IReader get (inout byte[] x); /// ditto
126 abstract IReader get (inout short[] x); /// ditto
127 abstract IReader get (inout int[] x); /// ditto
128 abstract IReader get (inout long[] x); /// ditto
129 abstract IReader get (inout ubyte[] x); /// ditto
130 abstract IReader get (inout ushort[] x); /// ditto
131 abstract IReader get (inout uint[] x); /// ditto
132 abstract IReader get (inout ulong[] x); /// ditto
133 abstract IReader get (inout float[] x); /// ditto
134 abstract IReader get (inout double[] x); /// ditto
135 abstract IReader get (inout real[] x); /// ditto
136 abstract IReader get (inout char[] x); /// ditto
137 abstract IReader get (inout wchar[] x); /// ditto
138 abstract IReader get (inout dchar[] x); /// ditto
139
140 /***********************************************************************
141
142 This is the mechanism used for binding arbitrary classes
143 to the IO system. If a class implements IReadable, it can
144 be used as a target for IReader get() operations. That is,
145 implementing IReadable is intended to transform any class
146 into an IReader adaptor for the content held therein.
147
148 ***********************************************************************/
149
150 abstract IReader get (IReadable);
151
152 alias void delegate (IReader) Closure;
153
154 abstract IReader get (Closure);
155
156 /***********************************************************************
157
158 Return the buffer associated with this reader
159
160 ***********************************************************************/
161
162 abstract IBuffer buffer ();
163
164 /***********************************************************************
165
166 Get the allocator to use for array management. Arrays are
167 generally allocated by the IReader, via configured managers.
168 A number of Allocator classes are available to manage memory
169 when reading array content. Alternatively, the application
170 may obtain responsibility for allocation by selecting one of
171 the NativeProtocol deriviatives and setting 'prefix' to be
172 false. The latter disables internal array management.
173
174 Gaining access to the allocator can expose some additional
175 controls. For example, some allocators benefit from a reset
176 operation after each data 'record' has been processed.
177
178 By default, an IReader will allocate each array from the
179 heap. You can change that by constructing the Reader
180 with an Allocator of choice. For instance, there is a
181 BufferSlice which will slice an array directly from
182 the buffer where possible. Also available is the record-
183 oriented HeaoSlice, which slices memory from within
184 a pre-allocated heap area, and should be reset by the client
185 code after each record has been read (to avoid unnecessary
186 growth).
187
188 See module tango.io.protocol.Allocator for more information
189
190 ***********************************************************************/
191
192 abstract IAllocator allocator ();
193 }
194
195 /*******************************************************************************
196
197 Any class implementing IReadable becomes part of the Reader framework
198
199 *******************************************************************************/
200
201 interface IReadable
202 {
203 void read (IReader input);
204 }
205