All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
src/include/aerospike/as_module.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 #pragma once
23 
24 #include <stdlib.h>
25 
26 #include <aerospike/as_aerospike.h>
27 #include <aerospike/as_stream.h>
28 #include <aerospike/as_result.h>
29 #include <aerospike/as_types.h>
30 #include <aerospike/as_logger.h>
31 #include <aerospike/as_udf_context.h>
32 
33 /*****************************************************************************
34  * TYPES
35  *****************************************************************************/
36 
37 struct as_module_s;
38 
39 /**
40  * Module events.
41  *
42  * as_module_event e;
43  * e.type = AS_MODULE_CONFIGURE;
44  * e.data.config = my_config;
45  */
46 
47 typedef enum as_module_event_type_e {
53 
54 typedef struct as_module_event_data_s {
55  void * config;
56  const char * filename;
58 
59 typedef struct as_module_event_s {
63 
64 typedef struct as_module_error_s {
65  uint8_t scope;
66  uint32_t code;
67  char message[1024];
68  char file[256];
69  uint32_t line;
70  char func[256];
72 
73 /**
74  * Module Interface
75  * Provide functions which interface with a module.
76  */
77 typedef struct as_module_hooks_s {
78 
79  /**
80  * Free resources used by the module.
81  */
82  int (* destroy)(struct as_module_s * m);
83 
84  /**
85  * Dispatch an event to the module.
86  */
87  int (* update)(struct as_module_s * m, as_module_event * e);
88 
89  /**
90  * Apply a functio to a record
91  */
92  int (* validate)(struct as_module_s * m, as_aerospike * as, const char * filename, const char * content, uint32_t size, as_module_error * err);
93 
94  /**
95  * Apply a function to a record
96  */
97  int (* apply_record)(struct as_module_s * m, as_udf_context *ctx, const char * filename, const char * function, as_rec * rec, as_list * args, as_result * res);
98 
99  /**
100  * Apply a function to a stream.
101  */
102  int (* apply_stream)(struct as_module_s * m, as_udf_context *ctx, const char * filename, const char * function, as_stream * istream, as_list * args, as_stream * ostream);
103 
105 
106 /**
107  * Module Structure.
108  * Contains pointer to module specific data and a pointer to the
109  * hooks that interface with the module.
110  *
111  * @field source contains module specific data.
112  * @field hooks contains functions that can be applied to the module.
113  */
114 typedef struct as_module_s {
115  const void * source;
118 } as_module;
119 
120 
121 /*****************************************************************************
122  * INLINE FUNCTIONS
123  *****************************************************************************/
124 
125 /**
126  * Get the source of the module.
127  *
128  * @param m the module to get the source from.
129  */
130 void * as_module_source(as_module * m);
131 
132 /**
133  * Get the logger for this module.
134  */
136 
137 /**
138  * Module Destroyer.
139  * This frees up the resources used by the module.
140  *
141  * Proxies to `m->hooks->destroy(m, ...)`
142  *
143  * @param m the module being initialized.
144  * @return 0 on success, otherwise 1
145  */
147 
148 /**
149  * Module Configurator.
150  * This configures and reconfigures the module. This can be called an
151  * arbitrary number of times during the lifetime of the server.
152  *
153  * Proxies to `m->hooks->configure(m, ...)`
154  *
155  * @param m the module being configured.
156  * @return 0 on success, otherwhise 1
157  */
158 int as_module_configure(as_module * m, void * c);
159 
160 /**
161  * Update a Module.
162  *
163  * Proxies to `m->hooks->update(m, ...)`
164  *
165  * @param m the module being initialized.
166  * @return 0 on success, otherwise 1
167  */
169 
170 /**
171  * Validates a UDF provided by a string.
172  *
173  * @param m Module from which the fqn will be resolved.
174  * @param as aerospike object to be used.
175  * @param filename The name of the udf module to be validated.
176  * @param content The content of the udf module to be validated.
177  * @param error The error string (1024 bytes). Should be preallocated. Will be an empty string if no error occurred.
178  *
179  * @return 0 on success, otherwise 1 on error.
180  */
181 int as_module_validate(as_module * m, as_aerospike * as, const char * filename, const char * content, uint32_t size, as_module_error * error);
182 
183 /**
184  * Applies a UDF to a stream with provided arguments.
185  *
186  * @param m Module from which the fqn will be resolved.
187  * @param ctx aerospike udf execution context
188  * @param filename The name of the udf module containing the function to be executed.
189  * @param function The name of the udf function to be executed.
190  * @param r record to apply to the function.
191  * @param args list of arguments for the function represented as vals
192  * @param result pointer to a val that will be populated with the result.
193  *
194  * @return 0 on success, otherwise 1
195  */
196 int as_module_apply_record(as_module * m, as_udf_context * ctx, const char * filename, const char * function, as_rec * r, as_list * args, as_result * res);
197 
198 /**
199  * Applies function to a stream and set of arguments. Pushes the results into an output stream.
200  *
201  * Proxies to `m->hooks->apply_stream(m, ...)`
202  *
203  * @param m Module from which the fqn will be resolved.
204  * @param ctx aerospike udf execution context
205  * @param filename The name of the udf module containing the function to be executed.
206  * @param function The name of the udf function to be executed.
207  * @param istream pointer to a readable stream, that will provides values.
208  * @param args list of arguments for the function represented as vals
209  * @param ostream pointer to a writable stream, that will be populated with results.
210  * @param result pointer to a val that will be populated with the result.
211  *
212  * @return 0 on success, otherwise 1
213  */
214 int as_module_apply_stream(as_module * m, as_udf_context * ctx, const char * filename, const char * function, as_stream * istream, as_list * args, as_stream * ostream);
215 
216 /**
217  * Return lua error in string format when error code is passed in
218  *
219  * @param errno The error code
220  */
221 char *as_module_err_string(int);
int as_module_validate(as_module *m, as_aerospike *as, const char *filename, const char *content, uint32_t size, as_module_error *error)
char * as_module_err_string(int)
void * as_module_source(as_module *m)
int as_module_apply_record(as_module *m, as_udf_context *ctx, const char *filename, const char *function, as_rec *r, as_list *args, as_result *res)
int as_module_apply_stream(as_module *m, as_udf_context *ctx, const char *filename, const char *function, as_stream *istream, as_list *args, as_stream *ostream)
#define error(fmt, args...)
int as_module_configure(as_module *m, void *c)
int as_module_destroy(as_module *m)
int as_module_update(as_module *m, as_module_event *e)
const as_module_hooks * hooks
as_logger * as_module_logger(as_module *m)