All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_stream.h
Go to the documentation of this file.
1 /******************************************************************************
2  * Copyright 2008-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 #pragma once
24 
25 #include <stdlib.h>
26 
27 #include <aerospike/as_val.h>
28 #include <aerospike/as_util.h>
29 
30 /******************************************************************************
31  * MACROS
32  *****************************************************************************/
33 
34 #define AS_STREAM_END ((void *) 0)
35 
36 /******************************************************************************
37  * TYPES
38  *****************************************************************************/
39 
40 struct as_stream_hooks_s;
41 
42 /**
43  * Stream Status Codes
44  */
45 typedef enum as_stream_status_e {
49 
50 /**
51  * Stream Interface
52  *
53  * To use the stream interface, you will need to create an instance
54  * via one of the implementations.
55  *
56  * @ingroup aerospike_t
57  */
58 typedef struct as_stream_s {
59 
60  /**
61  * Specifies whether the free() can be used
62  * on this stream.
63  */
64  bool free;
65 
66  /**
67  * Context data for the stream.
68  */
69  void * data;
70 
71  /**
72  * Hooks for the stream
73  */
74  const struct as_stream_hooks_s * hooks;
75 
76 } as_stream;
77 
78 /**
79  * Stream Hooks
80  *
81  * An implementation of `as_rec` should provide implementations for each
82  * of the hooks.
83  */
84 typedef struct as_stream_hooks_s {
85 
86  /**
87  * Destroy the stream.
88  */
89  int (* destroy)(as_stream * stream);
90 
91  /**
92  * Read the next value from the stream.
93  */
94  as_val * (* read)(const as_stream * stream);
95 
96  /**
97  * Write a value to the stream.
98  */
99  as_stream_status (* write)(const as_stream * stream, as_val * value);
100 
102 
103 /******************************************************************************
104  * INSTANCE FUNCTIONS
105  *****************************************************************************/
106 
107 /**
108  * Initializes a stack allocated as_stream for a given source and hooks.
109  *
110  * @param stream The stream to initialize.
111  * @param data The source feeding the stream
112  * @param hooks The hooks that interface with the source
113  *
114  * @return On success, the initialized stream. Otherwise NULL.
115  *
116  * @relatesalso as_stream
117  */
118 inline as_stream * as_stream_init(as_stream * stream, void * data, const as_stream_hooks * hooks)
119 {
120  if ( !stream ) return stream;
121 
122  stream->free = false;
123  stream->data = data;
124  stream->hooks = hooks;
125  return stream;
126 }
127 
128 /**
129  * Creates a new heap allocated as_stream for a given source and hooks.
130  *
131  * @param data The source feeding the stream
132  * @param hooks The hooks that interface with the source
133  *
134  * @return On success, a new stream. Otherwise NULL.
135  *
136  * @relatesalso as_stream
137  */
138 inline as_stream * as_stream_new(void * data, const as_stream_hooks * hooks)
139 {
140  as_stream * stream = (as_stream *) malloc(sizeof(as_stream));
141  if ( !stream ) return stream;
142 
143  stream->free = true;
144  stream->data = data;
145  stream->hooks = hooks;
146  return stream;
147 }
148 
149 /**
150  * Destroy the as_stream and associated resources.
151  *
152  * @param stream The stream to destroy.
153  *
154  * @return 0 on success, otherwise 1.
155  *
156  * @relatesalso as_stream
157  */
158 inline void as_stream_destroy(as_stream * stream)
159 {
160  as_util_hook(destroy, 1, stream);
161  if ( stream && stream->free ) {
162  free(stream);
163  }
164 }
165 
166 /******************************************************************************
167  * VALUE FUNCTIONS
168  *****************************************************************************/
169 
170 /**
171  * Get the source for the stream
172  *
173  * @param stream The stream to get the source from
174  *
175  * @return pointer to the source of the stream
176  *
177  * @relatesalso as_stream
178  */
179 inline void * as_stream_source(const as_stream * stream)
180 {
181  return (stream ? stream->data : NULL);
182 }
183 
184 /**
185  * Reads a value from the stream
186  *
187  * @param stream The stream to be read.
188  *
189  * @return the element read from the stream or STREAM_END
190  *
191  * @relatesalso as_stream
192  */
193 inline as_val * as_stream_read(const as_stream * stream)
194 {
195  return as_util_hook(read, NULL, stream);
196 }
197 
198 /**
199  * Is the stream readable? Tests whether the stream has a read function.
200  *
201  * @param stream The stream to test.
202  *
203  * @return true if the stream can be read from
204  *
205  * @relatesalso as_stream
206  */
207 inline bool as_stream_readable(const as_stream * stream)
208 {
209  return stream != NULL && stream->hooks != NULL && stream->hooks->read;
210 }
211 
212 /**
213  * Write a value to the stream
214  *
215  * @param stream The stream to write to.
216  * @param value The element to write to the stream.
217  *
218  * @return AS_STREAM_OK on success, otherwise is failure.
219  *
220  * @relatesalso as_stream
221  */
222 inline as_stream_status as_stream_write(const as_stream * stream, as_val * value)
223 {
224  return as_util_hook(write, AS_STREAM_ERR, stream, value);
225 }
226 
227 
228 /**
229  * Is the stream writable? Tests whether the stream has a write function.
230  *
231  * @param stream The stream to test.
232  *
233  * @return true if the stream can be written to.
234  *
235  * @relatesalso as_stream
236  */
237 inline bool as_stream_writable(const as_stream * stream)
238 {
239  return stream != NULL && stream->hooks != NULL && stream->hooks->write;
240 }