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