All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
modules/common/src/include/aerospike/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 #include <citrusleaf/alloc.h>
31 
32 /******************************************************************************
33  * MACROS
34  *****************************************************************************/
35 
36 #define AS_STREAM_END ((void *) 0)
37 
38 /******************************************************************************
39  * TYPES
40  *****************************************************************************/
41 
42 struct as_stream_hooks_s;
43 
44 /**
45  * Stream Status Codes
46  */
47 typedef enum as_stream_status_e {
51 
52 /**
53  * Stream Interface
54  *
55  * To use the stream interface, you will need to create an instance
56  * via one of the implementations.
57  *
58  * @ingroup aerospike_t
59  */
60 typedef struct as_stream_s {
61 
62  /**
63  * Specifies whether the cf_free() can be used
64  * on this stream.
65  */
66  bool free;
67 
68  /**
69  * Context data for the stream.
70  */
71  void * data;
72 
73  /**
74  * Hooks for the stream
75  */
76  const struct as_stream_hooks_s * hooks;
77 
78 } as_stream;
79 
80 /**
81  * Stream Hooks
82  *
83  * An implementation of `as_rec` should provide implementations for each
84  * of the hooks.
85  */
86 typedef struct as_stream_hooks_s {
87 
88  /**
89  * Destroy the stream.
90  */
91  int (* destroy)(as_stream * stream);
92 
93  /**
94  * Read the next value from the stream.
95  */
96  as_val * (* read)(const as_stream * stream);
97 
98  /**
99  * Write a value to the stream.
100  */
101  as_stream_status (* write)(const as_stream * stream, as_val * value);
102 
104 
105 /**
106  * Wrapper functions to ensure each CF allocation-related function call has a unique line.
107  */
108 void *as_stream_malloc(size_t size);
109 void as_stream_free(void *ptr);
110 
111 /******************************************************************************
112  * INSTANCE FUNCTIONS
113  *****************************************************************************/
114 
115 /**
116  * Initializes a stack allocated as_stream for a given source and hooks.
117  *
118  * @param stream The stream to initialize.
119  * @param data The source feeding the stream
120  * @param hooks The hooks that interface with the source
121  *
122  * @return On success, the initialized stream. Otherwise NULL.
123  *
124  * @relatesalso as_stream
125  */
126 static inline as_stream * as_stream_init(as_stream * stream, void * data, const as_stream_hooks * hooks)
127 {
128  if ( !stream ) return stream;
129 
130  stream->free = false;
131  stream->data = data;
132  stream->hooks = hooks;
133  return stream;
134 }
135 
136 /**
137  * Creates a new heap allocated as_stream for a given source and hooks.
138  *
139  * @param data The source feeding the stream
140  * @param hooks The hooks that interface with the source
141  *
142  * @return On success, a new stream. Otherwise NULL.
143  *
144  * @relatesalso as_stream
145  */
146 static inline as_stream * as_stream_new(void * data, const as_stream_hooks * hooks)
147 {
148  as_stream * stream = (as_stream *) as_stream_malloc(sizeof(as_stream));
149  if ( !stream ) return stream;
150 
151  stream->free = true;
152  stream->data = data;
153  stream->hooks = hooks;
154  return stream;
155 }
156 
157 /**
158  * Destroy the as_stream and associated resources.
159  *
160  * @param stream The stream to destroy.
161  *
162  * @return 0 on success, otherwise 1.
163  *
164  * @relatesalso as_stream
165  */
166 static inline void as_stream_destroy(as_stream * stream)
167 {
168  as_util_hook(destroy, 1, stream);
169  if ( stream && stream->free ) {
170  as_stream_free(stream);
171  }
172 }
173 
174 /******************************************************************************
175  * VALUE FUNCTIONS
176  *****************************************************************************/
177 
178 /**
179  * Get the source for the stream
180  *
181  * @param stream The stream to get the source from
182  *
183  * @return pointer to the source of the stream
184  *
185  * @relatesalso as_stream
186  */
187 static inline void * as_stream_source(const as_stream * stream)
188 {
189  return (stream ? stream->data : NULL);
190 }
191 
192 /**
193  * Reads a value from the stream
194  *
195  * @param stream The stream to be read.
196  *
197  * @return the element read from the stream or STREAM_END
198  *
199  * @relatesalso as_stream
200  */
201 static inline as_val * as_stream_read(const as_stream * stream)
202 {
203  return as_util_hook(read, NULL, stream);
204 }
205 
206 /**
207  * Is the stream readable? Tests whether the stream has a read function.
208  *
209  * @param stream The stream to test.
210  *
211  * @return true if the stream can be read from
212  *
213  * @relatesalso as_stream
214  */
215 static inline bool as_stream_readable(const as_stream * stream)
216 {
217  return stream != NULL && stream->hooks != NULL && stream->hooks->read;
218 }
219 
220 /**
221  * Write a value to the stream
222  *
223  * @param stream The stream to write to.
224  * @param value The element to write to the stream.
225  *
226  * @return AS_STREAM_OK on success, otherwise is failure.
227  *
228  * @relatesalso as_stream
229  */
230 static inline as_stream_status as_stream_write(const as_stream * stream, as_val * value)
231 {
232  return as_util_hook(write, AS_STREAM_ERR, stream, value);
233 }
234 
235 
236 /**
237  * Is the stream writable? Tests whether the stream has a write function.
238  *
239  * @param stream The stream to test.
240  *
241  * @return true if the stream can be written to.
242  *
243  * @relatesalso as_stream
244  */
245 static inline bool as_stream_writable(const as_stream * stream)
246 {
247  return stream != NULL && stream->hooks != NULL && stream->hooks->write;
248 }
void as_stream_free(void *ptr)
static as_stream * as_stream_init(as_stream *stream, void *data, const as_stream_hooks *hooks)
static as_stream * as_stream_new(void *data, const as_stream_hooks *hooks)
static as_stream_status as_stream_write(const as_stream *stream, as_val *value)
const struct as_stream_hooks_s * hooks
static as_val * as_stream_read(const as_stream *stream)
static bool as_stream_writable(const as_stream *stream)
static void * as_stream_source(const as_stream *stream)
static bool as_stream_readable(const as_stream *stream)
static void as_stream_destroy(as_stream *stream)
void * as_stream_malloc(size_t size)
#define as_util_hook(hook, default, object, args...)