ocean.util.container.queue.model.IUntypedQueue source code

1 /******************************************************************************
2 
3     An interface for a FIFO queue with items of unspecified type.
4 
5     This interface is deliberately designed to be as minimal as possible,
6     only covering the core functionality shared by the wide variety of possible
7     queue implementations. For example, even a basic pop function which returns
8     an item is not generic -- certain implementations may need to relinquish the
9     item after popping it, making a simple pop-then-return implementation
10     impossible. For this reason, some additional helper functions are provided,
11     which may be useful with some queue implementations.
12 
13     Copyright:
14         Copyright (c) 2009-2016 dunnhumby Germany GmbH.
15         All rights reserved.
16 
17     License:
18         Boost Software License Version 1.0. See LICENSE_BOOST.txt for details.
19         Alternatively, this file may be distributed under the terms of the Tango
20         3-Clause BSD License (see LICENSE_BSD.txt for details).
21 
22 *******************************************************************************/
23 
24 module ocean.util.container.queue.model.IUntypedQueue;
25 
26 import ocean.core.Array : copy;
27 
28 
29 /******************************************************************************
30 
31     An interface for a FIFO queue with items of unspecified type (opaque chunks
32     of data).
33 
34 *******************************************************************************/
35 
36 public interface IUntypedQueue
37 {
38     /**************************************************************************
39 
40         Returns:
41             true if queue is empty, false otherwise
42 
43     ***************************************************************************/
44 
45     bool empty ( );
46 
47 
48     /**************************************************************************
49 
50         Returns:
51             number of items in the queue
52 
53     ***************************************************************************/
54 
55     size_t length ( );
56 
57 
58     /**************************************************************************
59 
60         Returns:
61             number of bytes in the queue
62 
63     ***************************************************************************/
64 
65     size_t size ( );
66 
67 
68     /**************************************************************************
69 
70         Removes all items from the queue
71 
72     ***************************************************************************/
73 
74     void clear ( );
75 
76 
77     /**************************************************************************
78 
79         Pushes an item of `size` bytes to the queue. The caller should set the
80         returned item as desired
81 
82         Params:
83             size = number of bytes to push into queue
84 
85         Returns:
86             Newly pushed item, null if the item could not be pushed (see
87             documentation of implementing class for possible failure reasons)
88 
89     ***************************************************************************/
90 
91     void[] push ( size_t size );
92 
93 
94     /**************************************************************************
95 
96         Discards the item at the top of the queue.
97 
98     ***************************************************************************/
99 
100     void discardTop ( );
101 
102 
103     /**************************************************************************
104 
105         Returns:
106             The item at the top of the queue, null if the queue is empty
107 
108     ***************************************************************************/
109 
110     void[] top ( );
111 }
112 
113 
114 /******************************************************************************
115 
116     A helper function to push into IUntypedQueue.
117 
118     Note: this function performs a shallow copy of t into the queue.
119     If this is not desired, the caller class is to call `push()` method of
120     `IUntypedQueue` and apply desired logic on returned pointer.
121 
122     Params:
123         q = A queue to push into
124         t = An item to push into q
125 
126     Returns:
127         true if t pushed into q, false otherwise
128 
129 *******************************************************************************/
130 
131 public bool push ( IUntypedQueue q, in void[] t )
132 {
133     auto s = q.push(t.length);
134     if ( s is null ) return false;
135     s.copy(t);
136     return true;
137 }
138 
139 
140 /******************************************************************************
141 
142     A helper function to pop from IUntypedQueue.
143 
144     Note: this function performs a shallow copy of the popped item into t.
145     if this is not desired, the caller class is to call `top()` method of
146     `IUntypedQueue` and apply desired logic on returned pointer and then call
147     `discardTop()`.
148 
149     Params:
150         q = A queue to pop from
151         t = will hold the item popped from q, when function ends
152 
153     Returns:
154         true if top item was popped and copied to t, false otherwise
155 
156 *******************************************************************************/
157 
158 public bool pop ( IUntypedQueue q, ref void[] t )
159 {
160     auto p = q.top();
161     if ( p is null )
162     {
163         return false;
164     }
165     t.copy(p);
166     q.discardTop();
167     return true;
168 }