All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
target/Linux-x86_64/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_memtracker.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_aerospike * as, 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_aerospike * as, 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;
116  as_logger * logger;
117  as_memtracker * memtracker;
118  const as_module_hooks * hooks;
119 } as_module;
120 
121 
122 /*****************************************************************************
123  * INLINE FUNCTIONS
124  *****************************************************************************/
125 
126 /**
127  * Get the source of the module.
128  *
129  * @param m the module to get the source from.
130  */
131 void * as_module_source(as_module * m);
132 
133 /**
134  * Get the logger for this module.
135  */
137 
138 /**
139  * Module Destroyer.
140  * This frees up the resources used by the module.
141  *
142  * Proxies to `m->hooks->destroy(m, ...)`
143  *
144  * @param m the module being initialized.
145  * @return 0 on success, otherwise 1
146  */
148 
149 /**
150  * Module Configurator.
151  * This configures and reconfigures the module. This can be called an
152  * arbitrary number of times during the lifetime of the server.
153  *
154  * Proxies to `m->hooks->configure(m, ...)`
155  *
156  * @param m the module being configured.
157  * @return 0 on success, otherwhise 1
158  */
159 int as_module_configure(as_module * m, void * c);
160 
161 /**
162  * Update a Module.
163  *
164  * Proxies to `m->hooks->update(m, ...)`
165  *
166  * @param m the module being initialized.
167  * @return 0 on success, otherwise 1
168  */
170 
171 /**
172  * Validates a UDF provided by a string.
173  *
174  * @param m Module from which the fqn will be resolved.
175  * @param as aerospike object to be used.
176  * @param filename The name of the udf module to be validated.
177  * @param content The content of the udf module to be validated.
178  * @param error The error string (1024 bytes). Should be preallocated. Will be an empty string if no error occurred.
179  *
180  * @return 0 on success, otherwise 1 on error.
181  */
182 int as_module_validate(as_module * m, as_aerospike * as, const char * filename, const char * content, uint32_t size, as_module_error * error);
183 
184 /**
185  * Applies a UDF to a stream with provided arguments.
186  *
187  * @param m Module from which the fqn will be resolved.
188  * @param as aerospike object to be used.
189  * @param filename The name of the udf module containing the function to be executed.
190  * @param function The name of the udf function to be executed.
191  * @param r record to apply to the function.
192  * @param args list of arguments for the function represented as vals
193  * @param result pointer to a val that will be populated with the result.
194  *
195  * @return 0 on success, otherwise 1
196  */
197 int as_module_apply_record(as_module * m, as_aerospike * as, const char * filename, const char * function, as_rec * r, as_list * args, as_result * res);
198 
199 /**
200  * Applies function to a stream and set of arguments. Pushes the results into an output stream.
201  *
202  * Proxies to `m->hooks->apply_stream(m, ...)`
203  *
204  * @param m Module from which the fqn will be resolved.
205  * @param as aerospike object to be used.
206  * @param filename The name of the udf module containing the function to be executed.
207  * @param function The name of the udf function to be executed.
208  * @param istream pointer to a readable stream, that will provides values.
209  * @param args list of arguments for the function represented as vals
210  * @param ostream pointer to a writable stream, that will be populated with results.
211  * @param result pointer to a val that will be populated with the result.
212  *
213  * @return 0 on success, otherwise 1
214  */
215 int as_module_apply_stream(as_module * m, as_aerospike * as, const char * filename, const char * function, as_stream * istream, as_list * args, as_stream * ostream);
216 
217 /**
218  * Return lua error in string format when error code is passed in
219  *
220  * @param errno The error code
221  */
222 char *as_module_err_string(int);