View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.rng.examples.stress;
18  
19  import org.apache.commons.rng.UniformRandomProvider;
20  
21  import java.io.Closeable;
22  import java.io.IOException;
23  import java.io.OutputStream;
24  import java.nio.ByteOrder;
25  
26  /**
27   * A specialised data output class that combines the functionality of
28   * {@link java.io.DataOutputStream DataOutputStream} and
29   * {@link java.io.BufferedOutputStream BufferedOutputStream} to write byte data from a RNG
30   * to an OutputStream. Large blocks of byte data are written in a single operation for efficiency.
31   * The byte data endianness can be configured.
32   *
33   * <p>This class is the functional equivalent of:</p>
34   *
35   * <pre>
36   * <code>
37   * OutputStream out = ...
38   * UniformRandomProvider rng = ...
39   * int size = 2048;
40   * DataOutputStream sink = new DataOutputStream(new BufferedOutputStream(out, size * 4));
41   * for (int i = 0; i < size; i++) {
42   *    sink.writeInt(rng.nextInt());
43   * }
44   *
45   * // Replaced with
46   * RngDataOutput output = RngDataOutput.ofInt(out, size, ByteOrder.BIG_ENDIAN);
47   * output.write(rng);
48   * </code>
49   * </pre>
50   *
51   * <p>Use of this class avoids the synchronized write operations in
52   * {@link java.io.BufferedOutputStream BufferedOutputStream}. In particular it avoids the
53   * 4 synchronized write operations to
54   * {@link java.io.BufferedOutputStream#write(int) BufferedOutputStream#write(int)} that
55   * occur for each {@code int} value that is written to
56   * {@link java.io.DataOutputStream#writeInt(int) DataOutputStream#writeInt(int)}.</p>
57   */
58  abstract class RngDataOutput implements Closeable {
59      /** The data buffer. */
60      protected final byte[] buffer;
61  
62      /** The underlying output stream. */
63      private final OutputStream out;
64  
65      /**
66       * Write big-endian {@code int} data.
67       * <pre>
68       * 3210  ->  3210
69       * </pre>
70       */
71      private static class BIntRngDataOutput extends RngDataOutput {
72          /**
73           * @param out Output stream.
74           * @param size Buffer size.
75           */
76          BIntRngDataOutput(OutputStream out, int size) {
77              super(out, size);
78          }
79  
80          @Override
81          public void fillBuffer(UniformRandomProvider rng) {
82              for (int i = 0; i < buffer.length; i += 4) {
83                  writeIntBE(i, rng.nextInt());
84              }
85          }
86      }
87  
88      /**
89       * Write little-endian {@code int} data.
90       * <pre>
91       * 3210  ->  0123
92       * </pre>
93       */
94      private static class LIntRngDataOutput extends RngDataOutput {
95          /**
96           * @param out Output stream.
97           * @param size Buffer size.
98           */
99          LIntRngDataOutput(OutputStream out, int size) {
100             super(out, size);
101         }
102 
103         @Override
104         public void fillBuffer(UniformRandomProvider rng) {
105             for (int i = 0; i < buffer.length; i += 4) {
106                 writeIntLE(i, rng.nextInt());
107             }
108         }
109     }
110 
111     /**
112      * Write big-endian {@code long} data.
113      * <pre>
114      * 76543210  ->  76543210
115      * </pre>
116      */
117     private static class BLongRngDataOutput extends RngDataOutput {
118         /**
119          * @param out Output stream.
120          * @param size Buffer size.
121          */
122         BLongRngDataOutput(OutputStream out, int size) {
123             super(out, size);
124         }
125 
126         @Override
127         public void fillBuffer(UniformRandomProvider rng) {
128             for (int i = 0; i < buffer.length; i += 8) {
129                 writeLongBE(i, rng.nextLong());
130             }
131         }
132     }
133 
134     /**
135      * Write little-endian {@code long} data.
136      * <pre>
137      * 76543210  ->  01234567
138      * </pre>
139      */
140     private static class LLongRngDataOutput extends RngDataOutput {
141         /**
142          * @param out Output stream.
143          * @param size Buffer size.
144          */
145         LLongRngDataOutput(OutputStream out, int size) {
146             super(out, size);
147         }
148 
149         @Override
150         public void fillBuffer(UniformRandomProvider rng) {
151             for (int i = 0; i < buffer.length; i += 8) {
152                 writeLongLE(i, rng.nextLong());
153             }
154         }
155     }
156 
157     /**
158      * Write {@code long} data as two little-endian {@code int} values.
159      * <pre>
160      * 76543210  ->  4567  0123
161      * </pre>
162      *
163      * <p>This is a specialisation that allows the Java big-endian representation to be split
164      * into two little-endian values in the original order of upper then lower bits. In
165      * comparison the {@link LLongRngDataOutput} will output the same data as:
166      *
167      * <pre>
168      * 76543210  ->  0123  4567
169      * </pre>
170      */
171     private static class LLongAsIntRngDataOutput extends RngDataOutput {
172         /**
173          * @param out Output stream.
174          * @param size Buffer size.
175          */
176         LLongAsIntRngDataOutput(OutputStream out, int size) {
177             super(out, size);
178         }
179 
180         @Override
181         public void fillBuffer(UniformRandomProvider rng) {
182             for (int i = 0; i < buffer.length; i += 8) {
183                 writeLongAsIntLE(i, rng.nextLong());
184             }
185         }
186     }
187 
188     /**
189      * Create a new instance.
190      *
191      * @param out Output stream.
192      * @param size Buffer size.
193      */
194     RngDataOutput(OutputStream out, int size) {
195         this.out = out;
196         buffer = new byte[size];
197     }
198 
199     /**
200      * Write the configured amount of byte data from the specified RNG to the output.
201      *
202      * @param rng Source of randomness.
203      * @exception IOException if an I/O error occurs.
204      */
205     public void write(UniformRandomProvider rng) throws IOException {
206         fillBuffer(rng);
207         out.write(buffer);
208     }
209 
210     /**
211      * Fill the buffer from the specified RNG.
212      *
213      * @param rng Source of randomness.
214      */
215     public abstract void fillBuffer(UniformRandomProvider rng);
216 
217     /**
218      * Writes an {@code int} to the buffer as four bytes, high byte first (big-endian).
219      *
220      * @param index the index to start writing.
221      * @param value an {@code int} to be written.
222      */
223     final void writeIntBE(int index, int value) {
224         buffer[index    ] = (byte) (value >>> 24);
225         buffer[index + 1] = (byte) (value >>> 16);
226         buffer[index + 2] = (byte) (value >>> 8);
227         buffer[index + 3] = (byte) value;
228     }
229 
230     /**
231      * Writes an {@code int} to the buffer as four bytes, low byte first (little-endian).
232      *
233      * @param index the index to start writing.
234      * @param value an {@code int} to be written.
235      */
236     final void writeIntLE(int index, int value) {
237         buffer[index    ] = (byte) value;
238         buffer[index + 1] = (byte) (value >>> 8);
239         buffer[index + 2] = (byte) (value >>> 16);
240         buffer[index + 3] = (byte) (value >>> 24);
241     }
242 
243     /**
244      * Writes an {@code long} to the buffer as eight bytes, high byte first (big-endian).
245      *
246      * @param index the index to start writing.
247      * @param value an {@code long} to be written.
248      */
249     final void writeLongBE(int index, long value) {
250         buffer[index    ] = (byte) (value >>> 56);
251         buffer[index + 1] = (byte) (value >>> 48);
252         buffer[index + 2] = (byte) (value >>> 40);
253         buffer[index + 3] = (byte) (value >>> 32);
254         buffer[index + 4] = (byte) (value >>> 24);
255         buffer[index + 5] = (byte) (value >>> 16);
256         buffer[index + 6] = (byte) (value >>> 8);
257         buffer[index + 7] = (byte) value;
258     }
259 
260     /**
261      * Writes an {@code long} to the buffer as eight bytes, low byte first (big-endian).
262      *
263      * @param index the index to start writing.
264      * @param value an {@code long} to be written.
265      */
266     final void writeLongLE(int index, long value) {
267         buffer[index    ] = (byte) value;
268         buffer[index + 1] = (byte) (value >>> 8);
269         buffer[index + 2] = (byte) (value >>> 16);
270         buffer[index + 3] = (byte) (value >>> 24);
271         buffer[index + 4] = (byte) (value >>> 32);
272         buffer[index + 5] = (byte) (value >>> 40);
273         buffer[index + 6] = (byte) (value >>> 48);
274         buffer[index + 7] = (byte) (value >>> 56);
275     }
276 
277     /**
278      * Writes an {@code long} to the buffer as two integers of four bytes, each
279      * low byte first (big-endian).
280      *
281      * @param index the index to start writing.
282      * @param value an {@code long} to be written.
283      */
284     final void writeLongAsIntLE(int index, long value) {
285         buffer[index    ] = (byte) (value >>> 32);
286         buffer[index + 1] = (byte) (value >>> 40);
287         buffer[index + 2] = (byte) (value >>> 48);
288         buffer[index + 3] = (byte) (value >>> 56);
289         buffer[index + 4] = (byte) value;
290         buffer[index + 5] = (byte) (value >>> 8);
291         buffer[index + 6] = (byte) (value >>> 16);
292         buffer[index + 7] = (byte) (value >>> 24);
293     }
294 
295     @Override
296     public void close() throws IOException {
297         try (OutputStream ostream = out) {
298             ostream.flush();
299         }
300     }
301 
302     /**
303      * Create a new instance to write batches of data from
304      * {@link UniformRandomProvider#nextInt()} to the specified output.
305      *
306      * @param out Output stream.
307      * @param size Number of values to write.
308      * @param byteOrder Byte order.
309      * @return the data output
310      */
311     @SuppressWarnings("resource")
312     static RngDataOutput ofInt(OutputStream out, int size, ByteOrder byteOrder) {
313         // Ensure the buffer is positive and a factor of 4
314         final int bytes = Math.max(size * 4, 4);
315         return byteOrder == ByteOrder.LITTLE_ENDIAN ?
316             new LIntRngDataOutput(out, bytes) :
317             new BIntRngDataOutput(out, bytes);
318     }
319 
320     /**
321      * Create a new instance to write batches of data from
322      * {@link UniformRandomProvider#nextLong()} to the specified output.
323      *
324      * @param out Output stream.
325      * @param size Number of values to write.
326      * @param byteOrder Byte order.
327      * @return the data output
328      */
329     @SuppressWarnings("resource")
330     static RngDataOutput ofLong(OutputStream out, int size, ByteOrder byteOrder) {
331         // Ensure the buffer is positive and a factor of 8
332         final int bytes = Math.max(size * 8, 8);
333         return byteOrder == ByteOrder.LITTLE_ENDIAN ?
334             new LLongRngDataOutput(out, bytes) :
335             new BLongRngDataOutput(out, bytes);
336     }
337 
338     /**
339      * Create a new instance to write batches of data from
340      * {@link UniformRandomProvider#nextLong()} to the specified output as two sequential
341      * {@code int} values.
342      *
343      * <p>This will output the following bytes:</p>
344      *
345      * <pre>
346      * // Little-endian
347      * 76543210  ->  4567  0123
348      *
349      * // Big-endian
350      * 76543210  ->  7654  3210
351      * </pre>
352      *
353      * <p>This ensures the output from the generator is the original upper then lower order bits
354      * for each endianess.
355      *
356      * @param out Output stream.
357      * @param size Number of values to write.
358      * @param byteOrder Byte order.
359      * @return the data output
360      */
361     @SuppressWarnings("resource")
362     static RngDataOutput ofLongAsInt(OutputStream out, int size, ByteOrder byteOrder) {
363         // Ensure the buffer is positive and a factor of 8
364         final int bytes = Math.max(size * 8, 8);
365         return byteOrder == ByteOrder.LITTLE_ENDIAN ?
366             new LLongAsIntRngDataOutput(out, bytes) :
367             new BLongRngDataOutput(out, bytes);
368     }
369 }