1/**
2 * @copyright 2013 Couchbase, Inc.
3 *
4 * @author Filipe Manana  <filipe@couchbase.com>
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
7 * use this file except in compliance with the License. You may obtain a copy of
8 * the License at
9 *
10 *  http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
15 * License for the specific language governing permissions and limitations under
16 * the License.
17 **/
18
19/**
20 * This is the public, plain C interface to expose to the outside.
21 **/
22
23#ifndef _MAPREDUCE_H
24#define _MAPREDUCE_H
25
26#include "config.h"
27#include "visibility.h"
28#include <libcouchstore/visibility.h>
29
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35    typedef struct {
36        char *json;
37        int  length;
38    } mapreduce_json_t;
39
40    typedef struct {
41        mapreduce_json_t *values;
42        int              length;
43    } mapreduce_json_list_t;
44
45    typedef struct {
46        mapreduce_json_t key;
47        mapreduce_json_t value;
48    } mapreduce_kv_t;
49
50    typedef enum {
51        MAPREDUCE_SUCCESS,
52        MAPREDUCE_SYNTAX_ERROR,
53        MAPREDUCE_RUNTIME_ERROR,
54        MAPREDUCE_ALLOC_ERROR,
55        MAPREDUCE_INVALID_ARG,
56        MAPREDUCE_TIMEOUT
57    } mapreduce_error_t;
58
59    typedef struct {
60        mapreduce_kv_t *kvs;
61        int            length;
62    } mapreduce_kv_list_t;
63
64    typedef struct {
65        mapreduce_error_t error;
66        union {
67            /* valid if error is MAPREDUCE_SUCCESS */
68            mapreduce_kv_list_t kvs;
69            /* valid if error is other than MAPREDUCE_SUCCESS */
70            char                *error_msg;
71        } result;
72    } mapreduce_map_result_t;
73
74    typedef struct {
75        mapreduce_map_result_t *list;
76        int                    length;
77    } mapreduce_map_result_list_t;
78
79    /**
80     * This API needs to be called once per process to initialize
81     * v8 javascript engine. This needs to be called before
82     * any v8 APIs like creating v8 isolate and v8 context.
83     **/
84    LIBCOUCHSTORE_API
85    void initV8();
86
87    /**
88     * This API needs to be called once per process to cleanup
89     * v8 resources. This needs to be called after disposing all
90     * v8 thread contexts like v8 isolate and v8 context.
91     **/
92    LIBCOUCHSTORE_API
93    void deinitV8();
94
95    /**
96     * All mapreduce initialization are done in this function.
97     **/
98    LIBCOUCHSTORE_API
99    void mapreduce_init();
100
101    /**
102     * All mapreduce deinitialization are done in this function.
103     **/
104    LIBCOUCHSTORE_API
105    void mapreduce_deinit();
106
107    /**
108     * Creates terminator thread to kill long running map reduce tasks.
109     **/
110    LIBCOUCHSTORE_API
111    void init_terminator_thread();
112
113    /**
114     * Destroys terminator thread at the end of the process. Setting
115     * fatal_exit to true prevents the accidental initialization of
116     * terminator_thread in case of exit due to an Erlang signal.
117     **/
118    LIBCOUCHSTORE_API
119    void deinit_terminator_thread(bool fatal_exit);
120
121    /**
122     * If return value other than MAPREDUCE_SUCCESS, error_msg might be
123     * assigned an error message, for which the caller is responsible to
124     * deallocate via mapreduce_free_error_msg().
125     **/
126    LIBMAPREDUCE_API
127    mapreduce_error_t mapreduce_start_map_context(const char *map_functions[],
128                                                  int num_functions,
129                                                  void **context,
130                                                  char **error_msg);
131
132    /**
133     * If return value is MAPREDUCE_SUCCESS, the caller is responsible for
134     * free'ing result output parameter with a call to
135     * mapreduce_free_map_result_list().
136     */
137    LIBMAPREDUCE_API
138    mapreduce_error_t mapreduce_map(void *context,
139                                    const mapreduce_json_t *doc,
140                                    const mapreduce_json_t *meta,
141                                    mapreduce_map_result_list_t **result);
142
143    LIBMAPREDUCE_API
144    void mapreduce_free_json_list(mapreduce_json_list_t *list);
145
146    LIBMAPREDUCE_API
147    void mapreduce_free_json(mapreduce_json_t *value);
148
149    LIBMAPREDUCE_API
150    void mapreduce_free_map_result_list(mapreduce_map_result_list_t *list);
151
152    LIBMAPREDUCE_API
153    void mapreduce_free_error_msg(char *error_msg);
154
155    /**
156     * If return value other than MAPREDUCE_SUCCESS, error_msg might be
157     * assigned an error message, for which the caller is responsible to
158     * deallocate via mapreduce_free_error_msg().
159     **/
160    LIBMAPREDUCE_API
161    mapreduce_error_t mapreduce_start_reduce_context(const char *reduce_functions[],
162                                                     int num_functions,
163                                                     void **context,
164                                                     char **error_msg);
165
166    /**
167     * If return value other than MAPREDUCE_SUCCESS, error_msg might be
168     * assigned an error message, for which the caller is responsible to
169     * deallocate via mapreduce_free_error_msg().
170     *
171     * If return value is MAPREDUCE_SUCCESS, the caller is responsible for
172     * free'ing result output parameter with a call to
173     * mapreduce_free_json_list().
174     */
175    LIBMAPREDUCE_API
176    mapreduce_error_t mapreduce_reduce_all(void *context,
177                                           const mapreduce_json_list_t *keys,
178                                           const mapreduce_json_list_t *values,
179                                           mapreduce_json_list_t **result,
180                                           char **error_msg);
181
182    /**
183     * If return value other than MAPREDUCE_SUCCESS, error_msg might be
184     * assigned an error message, for which the caller is responsible to
185     * deallocate via mapreduce_free_error_msg().
186     *
187     * If return value is MAPREDUCE_SUCCESS, the caller is responsible for
188     * free'ing result output parameter with a call to
189     * mapreduce_free_json().
190     **/
191    LIBMAPREDUCE_API
192    mapreduce_error_t mapreduce_reduce(void *context,
193                                       int reduceFunNum,
194                                       const mapreduce_json_list_t *keys,
195                                       const mapreduce_json_list_t *values,
196                                       mapreduce_json_t **result,
197                                       char **error_msg);
198
199    /**
200     * If return value other than MAPREDUCE_SUCCESS, error_msg might be
201     * assigned an error message, for which the caller is responsible to
202     * deallocate via mapreduce_free_error_msg().
203     *
204     * If return value is MAPREDUCE_SUCCESS, the caller is responsible for
205     * free'ing result output parameter with a call to
206     * mapreduce_free_json().
207     **/
208    LIBMAPREDUCE_API
209    mapreduce_error_t mapreduce_rereduce(void *context,
210                                         int reduceFunNum,
211                                         const mapreduce_json_list_t *reductions,
212                                         mapreduce_json_t **result,
213                                         char **error_msg);
214
215    LIBMAPREDUCE_API
216    void mapreduce_free_context(void *context);
217
218    LIBMAPREDUCE_API
219    void mapreduce_set_timeout(unsigned int seconds);
220
221
222#ifdef __cplusplus
223}
224#endif
225
226#endif
227