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-2016 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at 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, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 
18 #pragma once
19 
20 #include <stdlib.h>
21 
22 #include <aerospike/as_val.h>
23 #include <aerospike/as_util.h>
24 
25 #include <citrusleaf/alloc.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /******************************************************************************
32  * MACROS
33  *****************************************************************************/
34 
35 #define AS_STREAM_END ((void *) 0)
36 
37 /******************************************************************************
38  * TYPES
39  *****************************************************************************/
40 
41 struct as_stream_hooks_s;
42 
43 /**
44  * Stream Status Codes
45  */
46 typedef enum as_stream_status_e {
50 
51 /**
52  * Stream Interface
53  *
54  * To use the stream interface, you will need to create an instance
55  * via one of the implementations.
56  *
57  * @ingroup aerospike_t
58  */
59 typedef struct as_stream_s {
60 
61  /**
62  * Specifies whether the cf_free() can be used
63  * on this stream.
64  */
65  bool free;
66 
67  /**
68  * Context data for the stream.
69  */
70  void * data;
71 
72  /**
73  * Hooks for the stream
74  */
75  const struct as_stream_hooks_s * hooks;
76 
77 } as_stream;
78 
79 /**
80  * Stream Hooks
81  *
82  * An implementation of `as_rec` should provide implementations for each
83  * of the hooks.
84  */
85 typedef struct as_stream_hooks_s {
86 
87  /**
88  * Destroy the stream.
89  */
90  int (* destroy)(as_stream * stream);
91 
92  /**
93  * Read the next value from the stream.
94  */
95  as_val * (* read)(const as_stream * stream);
96 
97  /**
98  * Write a value to the stream.
99  */
100  as_stream_status (* write)(const as_stream * stream, as_val * value);
101 
103 
104 /**
105  * Wrapper functions to ensure each CF allocation-related function call has a unique line.
106  */
107 void *as_stream_malloc(size_t size);
108 void as_stream_free(void *ptr);
109 
110 /******************************************************************************
111  * INSTANCE FUNCTIONS
112  *****************************************************************************/
113 
114 /**
115  * Initializes a stack allocated as_stream for a given source and hooks.
116  *
117  * @param stream The stream to initialize.
118  * @param data The source feeding the stream
119  * @param hooks The hooks that interface with the source
120  *
121  * @return On success, the initialized stream. Otherwise NULL.
122  *
123  * @relatesalso as_stream
124  */
125 static inline as_stream * as_stream_init(as_stream * stream, void * data, const as_stream_hooks * hooks)
126 {
127  if ( !stream ) return stream;
128 
129  stream->free = false;
130  stream->data = data;
131  stream->hooks = hooks;
132  return stream;
133 }
134 
135 /**
136  * Creates a new heap allocated as_stream for a given source and hooks.
137  *
138  * @param data The source feeding the stream
139  * @param hooks The hooks that interface with the source
140  *
141  * @return On success, a new stream. Otherwise NULL.
142  *
143  * @relatesalso as_stream
144  */
145 static inline as_stream * as_stream_new(void * data, const as_stream_hooks * hooks)
146 {
147  as_stream * stream = (as_stream *) as_stream_malloc(sizeof(as_stream));
148  if ( !stream ) return stream;
149 
150  stream->free = true;
151  stream->data = data;
152  stream->hooks = hooks;
153  return stream;
154 }
155 
156 /**
157  * Destroy the as_stream and associated resources.
158  *
159  * @param stream The stream to destroy.
160  *
161  * @return 0 on success, otherwise 1.
162  *
163  * @relatesalso as_stream
164  */
165 static inline void as_stream_destroy(as_stream * stream)
166 {
167  as_util_hook(destroy, 1, stream);
168  if ( stream && stream->free ) {
169  as_stream_free(stream);
170  }
171 }
172 
173 /******************************************************************************
174  * VALUE FUNCTIONS
175  *****************************************************************************/
176 
177 /**
178  * Get the source for the stream
179  *
180  * @param stream The stream to get the source from
181  *
182  * @return pointer to the source of the stream
183  *
184  * @relatesalso as_stream
185  */
186 static inline void * as_stream_source(const as_stream * stream)
187 {
188  return (stream ? stream->data : NULL);
189 }
190 
191 /**
192  * Reads a value from the stream
193  *
194  * @param stream The stream to be read.
195  *
196  * @return the element read from the stream or STREAM_END
197  *
198  * @relatesalso as_stream
199  */
200 static inline as_val * as_stream_read(const as_stream * stream)
201 {
202  return as_util_hook(read, NULL, stream);
203 }
204 
205 /**
206  * Is the stream readable? Tests whether the stream has a read function.
207  *
208  * @param stream The stream to test.
209  *
210  * @return true if the stream can be read from
211  *
212  * @relatesalso as_stream
213  */
214 static inline bool as_stream_readable(const as_stream * stream)
215 {
216  return stream != NULL && stream->hooks != NULL && stream->hooks->read;
217 }
218 
219 /**
220  * Write a value to the stream
221  *
222  * @param stream The stream to write to.
223  * @param value The element to write to the stream.
224  *
225  * @return AS_STREAM_OK on success, otherwise is failure.
226  *
227  * @relatesalso as_stream
228  */
229 static inline as_stream_status as_stream_write(const as_stream * stream, as_val * value)
230 {
231  return as_util_hook(write, AS_STREAM_ERR, stream, value);
232 }
233 
234 
235 /**
236  * Is the stream writable? Tests whether the stream has a write function.
237  *
238  * @param stream The stream to test.
239  *
240  * @return true if the stream can be written to.
241  *
242  * @relatesalso as_stream
243  */
244 static inline bool as_stream_writable(const as_stream * stream)
245 {
246  return stream != NULL && stream->hooks != NULL && stream->hooks->write;
247 }
248 
249 #ifdef __cplusplus
250 } // end extern "C"
251 #endif
void as_stream_free(void *ptr)
static as_stream * as_stream_init(as_stream *stream, void *data, const as_stream_hooks *hooks)
Definition: as_stream.h:125
bool free
Definition: as_stream.h:65
static as_stream * as_stream_new(void *data, const as_stream_hooks *hooks)
Definition: as_stream.h:145
Definition: as_val.h:57
as_stream_status
Definition: as_stream.h:46
static as_stream_status as_stream_write(const as_stream *stream, as_val *value)
Definition: as_stream.h:229
void * data
Definition: as_stream.h:70
static as_val * as_stream_read(const as_stream *stream)
Definition: as_stream.h:200
#define as_util_hook(hook, default, object, args...)
Definition: as_util.h:36
static bool as_stream_writable(const as_stream *stream)
Definition: as_stream.h:244
static void * as_stream_source(const as_stream *stream)
Definition: as_stream.h:186
const struct as_stream_hooks_s * hooks
Definition: as_stream.h:75
uint8_t data[]
Definition: as_proto.h:1090
static bool as_stream_readable(const as_stream *stream)
Definition: as_stream.h:214
static void as_stream_destroy(as_stream *stream)
Definition: as_stream.h:165
void * as_stream_malloc(size_t size)