1/* -*- mode: C++; c-basic-offset: 4; indent-tabs-mode: nil -*- */
2// vim: ft=cpp:expandtab:ts=8:sw=4:softtabstop=4:
3#ident "$Id$"
4/*======
5This file is part of PerconaFT.
6
7
8Copyright (c) 2006, 2015, Percona and/or its affiliates. All rights reserved.
9
10 PerconaFT is free software: you can redistribute it and/or modify
11 it under the terms of the GNU General Public License, version 2,
12 as published by the Free Software Foundation.
13
14 PerconaFT is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with PerconaFT. If not, see <http://www.gnu.org/licenses/>.
21
22----------------------------------------
23
24 PerconaFT is free software: you can redistribute it and/or modify
25 it under the terms of the GNU Affero General Public License, version 3,
26 as published by the Free Software Foundation.
27
28 PerconaFT is distributed in the hope that it will be useful,
29 but WITHOUT ANY WARRANTY; without even the implied warranty of
30 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 GNU Affero General Public License for more details.
32
33 You should have received a copy of the GNU Affero General Public License
34 along with PerconaFT. If not, see <http://www.gnu.org/licenses/>.
35======= */
36
37#ident "Copyright (c) 2006, 2015, Percona and/or its affiliates. All rights reserved."
38
39#pragma once
40
41/*
42Create and set up a loader.
43 - The loader will operate in environment env, and the load will happen within transaction txn.
44 - You must remember to close (or abort) the loader eventually (otherwise the resulting DBs will
45 not be valid, and you will have a memory leak).
46 - The number of databases to be loaded is N.
47 - The databases must already be open, and their handles are passed in in the array dbs.
48 In particular dbs[i] is the ith database.
49 - The loader will work right whether the DBs are empty or full. However if any of the DBs are not empty,
50 it may not be fast (e.g., the loader may simply perform DB->put() operations).
51 - For each row that is put into the loader, for i over each of the N DBs, generate_row is invoked on the
52 row to generate a secondary row.
53 - The DBTs passed to generate_row() will have the DB_DBT_REALLOC flag set, and the extract
54 function should realloc the memory passed in. The ulen field indicates how large the realloc'd
55 storage is, and if the extract function does perform a realloc it should update the ulen field.
56 - We require that the extract function always return 0.
57 - The generate_row function must be thread safe.
58 - Whenever two rows in dbs[i] need to be compared we use that db's comparison function. The
59 comparison function must be thread safe.
60 - DBs must have been set up with descriptors and comparison functions before calling any extract
61 or compare functions.
62 - loader_flags is used to specify loader specific behavior. For instance, LOADER_USE_PUTS tells the
63 loader to use traditional puts to save disk space while loading (at the cost of performance)
64 - The new loader is returned in *blp.
65
66 Modifies: :: env, txn, blp, and dbs.
67*/
68int toku_loader_create_loader(DB_ENV *env, DB_TXN *txn, DB_LOADER **blp, DB *src_db, int N, DB *dbs[/*N*/], uint32_t db_flags[/*N*/], uint32_t dbt_flags[/*N*/], uint32_t loader_flags, bool check_empty);
69
70
71/*
72Set a error callback.
73 - If at any point during the load the system notices that an error has occurred, error information is recorded.
74 - The callback function may be called during DB_LOADER->close() or DB_LOADER->abort(), at which time the error
75 information is returned.
76 - A key-val pair for one of the errors is returned along with the db, and the index i indicating which db
77 had the problem.
78 - This function will be called at most once (so even if there are many problems, only one call will be made.)
79 - If a duplicate is discovered, the error is DB_KEYEXIST.
80 - The error_extra passed at the time of set_error_callback is the value passed as the error_extra when an error occurs.
81*/
82int toku_loader_set_error_callback(DB_LOADER *loader, void (*error_cb)(DB *db, int i, int err, DBT *key, DBT *val, void *error_extra), void *error_extra);
83
84
85/*
86Set the polling function.
87 - During the DB_LOADER->close operation, the poll function is called periodically.
88 - If it ever returns nonzero, then the loader stops as soon as possible.
89 - The poll function is called with the extra passed into the loader create function.
90 - A floating point number is also returned, which ranges from 0.0 to 1.0, indicating progress. Progress of 0.0 means
91 no progress so far. Progress of 0.5 means that the job is about half done. Progress of 1.0 means the job is done.
92 The progress is just an estimate.
93*/
94int toku_loader_set_poll_function(DB_LOADER *loader, int (*poll_func)(void *poll_extra, float progress), void *poll_extra);
95
96
97/*
98Give a row to the loader.
99 - Returns zero if no error, non-zero if error.
100 - When the application sees a non-zero return from put(), it must abort(), which would then call the error callback.
101 - Once put() returns a non-zero value, any loader calls other than abort() are unsupported and will result in undefined behavior.
102*/
103int toku_loader_put(DB_LOADER *loader, DBT *key, DBT *val);
104
105
106/*
107Finish the load,
108 - Take all the rows and put them into dictionaries which are returned as open handlers through the original dbs array.
109 - Frees all the memory allocated by the loader.
110 - You may not use the loader handle again after calling close.
111 - The system will return an DB_KEYEXIST if in any of the resulting databases, there are two different rows with keys
112 that compare to be equal (and the duplicate callback function, if set, is called first).
113 - If the polling function has been set, the loader will periodically call the polling function. If the polling function
114 ever returns a nonzero value, then the loader will return immediately, possibly with the dictionaries in some
115 inconsistent state. (To get them to a consistent state, the enclosing transaction should abort.)
116 - To free the resources used by a loader, either DB_LOADER->close or DB_LOADER->abort must be called. After calling either
117 of those functions, no further loader operations can be performed with that loader.
118 - The DBs remain open after the loader is closed.
119*/
120int toku_loader_close(DB_LOADER *loader);
121
122
123/*
124Abort the load,
125 - Possibly leave none, some, or all of the puts in effect. You may need to abort the enclosing transaction to get
126 back to a sane state.
127 - To free the resources used by a loader, either DB_LOADER->close or DB_LOADER->abort must be called. After calling either
128 of those functions, no further loader operations can be performed with that loader.
129 - The DBs remain open after the loader is aborted.
130 */
131int toku_loader_abort(DB_LOADER *loader);
132
133// Remove any loader temp files that may have been left from a crashed system
134int toku_loader_cleanup_temp_files(DB_ENV *env);
135
136
137typedef enum {
138 LOADER_CREATE = 0, // number of loaders successfully created
139 LOADER_CREATE_FAIL, // number of calls to toku_loader_create_loader() that failed
140 LOADER_PUT, // number of calls to toku_loader_put() that succeeded
141 LOADER_PUT_FAIL, // number of calls to toku_loader_put() that failed
142 LOADER_CLOSE, // number of calls to toku_loader_close()
143 LOADER_CLOSE_FAIL, // number of calls to toku_loader_close() that failed
144 LOADER_ABORT, // number of calls to toku_loader_abort()
145 LOADER_CURRENT, // number of loaders currently in existence
146 LOADER_MAX, // max number of loaders that ever existed simultaneously
147 LOADER_STATUS_NUM_ROWS
148} loader_status_entry;
149
150typedef struct {
151 bool initialized;
152 TOKU_ENGINE_STATUS_ROW_S status[LOADER_STATUS_NUM_ROWS];
153} LOADER_STATUS_S, *LOADER_STATUS;
154
155
156void toku_loader_get_status(LOADER_STATUS s);
157