File: /home/oboss/Users/gec/sources/Basic_Services/Source_Data/source_data_stream.ads
1 --% Compilation Unit: Source_Data_Stream
2 --
3 --% Category: Package Declaration
4 --
5 --% Release: $Name: $
6 --
7 --% Version: $Revision: 2.1 $
8 --
9 --% Author: $Author: jhl $
10 --
11 --% Revision Log:
12 -- $Log: source_data_stream.ads,v $
13 -- Revision 2.1 2003/10/09 11:05:17 jhl
14 -- Added Service 13 And 19
15 --
16 -- Revision 2.0.4.1 2003/10/08 14:51:12 jhl
17 -- Added subprograms Share and Deallocate for read streams.
18 -- Updated spec for Make_Read_Stream to comply to the functionality.
19 --
20 -- Revision 2.0 2003/04/04 08:50:18 gec
21 -- Initial release of source files serving as baseline for OBOSS-III project.
22 --
23 -- Revision 1.1.1.1 2003/04/04 08:13:04 gec
24 -- Imported using TkCVS
25 --
26 --
27 --
28 --% Project: OBOSS
29 --
30 --% Copyright (C) 2003 by Terma A/S
31 -- Proprietary and intellectual rights of Terma A/S, Denmark,
32 -- are involved in the subject-matter of this material and
33 -- all manufacturing, reproduction, use, disclosure, and
34 -- sales rights pertaining to such subject-matter are
35 -- expressly reserved. This material is submitted for a
36 -- specific purpose as agreed, and the recipient by
37 -- accepting this material agrees that this material will
38 -- not be used, copied, or reproduced in whole or in part
39 -- nor its contents revealed in any manner or to any person,
40 -- except to meet the purpose for which it was submitted and
41 -- subject to the terms of the agreement.
42 --
43 --% Target Dependencies:
44 -- None
45 --% Compiler Dependencies:
46 -- None
47
48 --~-----------------------------------------------------------------------------
49
50 with System;
51 with Basic_Types;
52 with Cell_Stream;
53 with Source_Data_Manager;
54 package Source_Data_Stream is
55
56 --% Library Package:
57 -- Implementation of stream data type used for representation of source
58 --+ data as defined by the packet utilisation standard. Put and Get
59 --+ operations are provided based on memory addresses for objects to be
60 --+ read or written.
61 -- Manages a heap of small source data streams and large source data
62 --+ streams (i.e. buffers)
63 --% Active Tasks:
64 --> None
65 --% Passive Tasks:
66 --> Source_Data_Manager.Small_Cell_Pool.Store_Manager.Allocator - Critical
67 --+ region protecting heap of small source data streams
68 --> Source_Data_Manager.Large_Cell_Pool.Store_Manager.Allocator - Critical
69 --+ region protecting heap of large source data streams
70
71 -- Possible bit-sizes for source data streams.
72 subtype Allocation_Size is Source_Data_Manager.Allocation_Size;
73
74 -- Representation of source data read streams and source data write
75 --+ streams.
76 type Read_Stream is private;
77 type Write_Stream is private;
78
79 -- Write_Stream_Exhausted is raised by a Put operation on a write stream
80 --+ when end of stream is met before the required number of bits is
81 --+ written.
82 Write_Stream_Exhausted : exception;
83
84 -- Read_Stream_Exhausted is raised by a Get operation on a read stream when
85 --+ the end of stream is met before the required number of bits is read.
86 Read_Stream_Exhausted : exception;
87
88 -- Not_Allocated indicates that an operation has been performed on an
89 --+ un-allocated read-stream or write-stream.
90 Not_Allocated : exception renames Source_Data_Manager.Not_Allocated;
91
92 -- No_Streams_Available indicates that an Allocate operation has failed due
93 --+ to lack of free streams.
94 No_Streams_Available : exception renames Source_Data_Manager.
95 No_Buffers_Available;
96
97 --% Subprogram:
98 -- Allocate write stream able to contain Size bits of data.
99 -- Resulting stream returned in Stream.
100 --% Parameter Constraints:
101 --> None
102 --% Exceptions Raised:
103 --> No_Streams_Available - Heap of streams has been exhausted.
104 procedure Allocate
105 (
106 Stream : out Write_Stream;
107 Size : in Allocation_Size);
108
109 --% Subprogram:
110 -- Share the write stream.
111 -- Implies that write stream will not be truely deallocated until the
112 --+ original allocator and any share-holders has called Deallocate.
113 --% Parameter Constraints:
114 --> None
115 --% Exceptions Raised:
116 --> Not_Allocated - Stream has not been allocated
117 procedure Share
118 (Stream : in Write_Stream);
119
120 --% Subprogram:
121 -- Share the read stream.
122 -- Implies that read stream will not be truely deallocated until the
123 --+ original allocator and any share-holders has called Deallocate.
124 --% Parameter Constraints:
125 --> None
126 --% Exceptions Raised:
127 --> Not_Allocated - Stream has not been allocated
128 procedure Share
129 (Stream : in Read_Stream);
130
131 --% Subprogram:
132 -- Deallocate the write stream.
133 -- Stream will not be truely deallocated until the original allocator and
134 --+ any share-holders has called Deallocate.
135 --% Parameter Constraints:
136 --> None
137 --% Exceptions Raised:
138 --> Not_Allocated - Stream is not currently allocated
139 procedure Deallocate
140 (Stream : in Write_Stream);
141
142 --% Subprogram:
143 -- Deallocate the read stream.
144 -- Stream will not be truely deallocated until the original allocator and
145 --+ any share-holders has called Deallocate.
146 --% Parameter Constraints:
147 --> None
148 --% Exceptions Raised:
149 --> Not_Allocated - Stream is not currently allocated
150 procedure Deallocate
151 (Stream : in Read_Stream);
152
153 --% Subprogram:
154 -- Append contents of Source read-stream at the end of Destination
155 --+ write-stream.
156 --% Parameter Constraints:
157 --> None
158 --% Exceptions Raised:
159 --> Not_Allocated - Either Source or Destination is not currently
160 --+ allocated
161 procedure Append
162 (Destination : in out Write_Stream;
163 Source : in Read_Stream);
164
165 --% Subprogram:
166 -- Construct a write stream containing the byte image Img.
167 -- NOTE: This operation is potentially blocking. If no stream is
168 --+ available, the caller will be suspended until this is the case.
169 --% Parameter Constraints:
170 --> None
171 --% Exceptions Raised:
172 --> No_Streams_Available - Heap of streams has been exhausted.
173 function Make_Stream_From_Image
174 (Img : Basic_Types.Byte_Array)
175 return Write_Stream;
176
177 --% Subprogram:
178 -- Construct a byte image containing a copy of the raw data in Rstream.
179 -- NOTE: Rstream is NOT updated to reflect the bytes read to construct
180 --+ result value.
181 --% Parameter Constraints:
182 --> None
183 --% Exceptions Raised:
184 --> Not_Allocated - Rstream is not currently allocated.
185 function Make_Image_From_Stream
186 (Rstream : Read_Stream)
187 return Basic_Types.Byte_Array;
188
189 --% Subprogram:
190 -- Append object at address Addr at the end of Stream.
191 -- Type_Size is the bit-size of the type to which the object belongs
192 --+ (i.e. the number of bits to be appended).
193 -- Object_Size is the bit-size of the 'containing object', i.e. the Ada
194 --+ object situated at address Addr.
195 --% Parameter Constraints:
196 --> Object_Size - Type_Size shall be less than or equal to Object_Size
197 --% Exceptions Raised:
198 --> Not_Allocated - Stream is not currently allocated.
199 --> Write_Stream_Exhausted - End of stream was met while appending
200 --+ object.
201 procedure Put
202 (
203 Stream : in out Write_Stream;
204 Addr : in System.Address;
205 Type_Size : in Basic_Types.Bit_Size;
206 Object_Size : in Basic_Types.Bit_Size);
207
208 --% Subprogram:
209 -- Append contents of byte array Img at the end of write stream Stream.
210 --% Parameter Constraints:
211 --> Img - If Img'Length = 0 then Stream may be unallocated.
212 --% Exceptions Raised:
213 --> Not_Allocated - Stream is not currently allocated.
214 --> Write_Stream_Exhausted - End of stream was met while appending Img.
215 procedure Put
216 (Stream : in out Write_Stream;
217 Img : in Basic_Types.Byte_Array);
218
219 --% Subprogram:
220 -- Construct a read stream on write stream Stream.
221 -- Access to read stream will access data previously written to write
222 --+ stream.
223 -- This is not a copy operation. The resulting read stream access the
224 --+ same data as the write stream. I.e. updates of the write stream will
225 --+ can be read from the read stream.
226 --% Parameter Constraints:
227 --> None
228 --% Exceptions Raised:
229 --> Not_Allocated - Stream is not currently allocated.
230 function Make_Read_Stream
231 (Stream : Write_Stream)
232 return Read_Stream;
233
234 --% Subprogram:
235 -- Read object of size Type_Size from head of read stream Stream and
236 --+ place it in an Ada object of size Object_Size at address Addr.
237 -- If Sign_Extend = true then sign bit for data read from stream is
238 --+ extended to Object_Size (re. 2's omplement representation of negative
239 --+ numbers).
240 --% Parameter Constraints:
241 --> Object_Size - Type_Size shall be less than or equal to Object_Size
242 --% Exceptions Raised:
243 --> Not_Allocated - Stream is not currently allocated.
244 --> Read_Stream_Exhausted - End of stream was met while reading object.
245 procedure Get
246 (
247 Stream : in out Read_Stream;
248 Addr : in System.Address;
249 Type_Size : in Basic_Types.Bit_Size;
250 Object_Size : in Basic_Types.Bit_Size;
251 Sign_Extend : in Boolean);
252
253 --% Subprogram:
254 -- Read byte image Img from head of read stream Stream.
255 -- Number of bytes to be read are given by Img'Length.
256 --% Parameter Constraints:
257 --> None
258 --% Exceptions Raised:
259 --> Not_Allocated - Rstream is not currently allocated.
260 --> Read_Stream_Exhausted - End of stream was met while reading Img.
261 procedure Get
262 (Rstream : in out Read_Stream;
263 Img : out Basic_Types.Byte_Array);
264
265 --% Subprogram:
266 -- Provides number of unread bits in read stream Stream.
267 -- Returns zero if we are at end of stream.
268 --% Parameter Constraints:
269 --> None
270 --% Exceptions Raised:
271 --> Not_Allocated - Stream is not currently allocated.
272 function Bits_In_Stream
273 (Stream : Read_Stream)
274 return Basic_Types.Bit_Size;
275
276
277 --% Subprogram:
278 -- Provides number of bits that has been written to write stream Stream.
279 -- Returns zero if stream is empty, i.e. nothing has been written.
280 --% Parameter Constraints:
281 --> None
282 --% Exceptions Raised:
283 --> Not_Allocated - Stream is not currently allocated.
284 function Bits_In_Stream
285 (Stream : Write_Stream)
286 return Basic_Types.Bit_Size;
287
288 private
289
290 subtype Optional_Location is Source_Data_Manager.Optional_Location;
291
292 subtype Put_Position is Cell_Stream.Put_Position;
293 subtype Get_Position is Cell_Stream.Get_Position;
294
295 type Write_Stream is
296 record
297 Loc : Optional_Location; -- Reference to stream in
298 --+ Source_Data_Manager
299 Pp : Put_Position; -- Bit position for next
300 --+ write.
301 end record;
302
303 type Read_Stream is
304 record
305 Stream : Write_Stream; -- Write stream to be
306 --+ read from.
307 Gp : Get_Position; -- First unread bit.
308 end record;
309
310 end Source_Data_Stream;
311
312 --~-----------------------------------------------------------------------------
313