Drizzled Public API Documentation

storage_engine.h
1 /* -*- mode: c++; c-basic-offset: 2; indent-tabs-mode: nil; -*-
2  * vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
3  *
4  * Copyright (C) 2008 Sun Microsystems, Inc.
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; version 2 of the License.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18  */
19 
20 #pragma once
21 
22 #include <drizzled/definitions.h>
23 #include <drizzled/error_t.h>
24 #include <drizzled/handler_structs.h>
25 #include <drizzled/message.h>
26 #include <drizzled/message/cache.h>
27 #include <drizzled/plugin.h>
28 #include <drizzled/plugin/monitored_in_transaction.h>
29 #include <drizzled/plugin/plugin.h>
30 #include <drizzled/sql_string.h>
31 
32 #include <bitset>
33 #include <string>
34 #include <vector>
35 #include <set>
36 
37 #include <drizzled/visibility.h>
38 
39 namespace drizzled {
40 
41 struct HASH;
42 
43 typedef bool (stat_print_fn)(Session *session, const char *type, uint32_t type_len,
44  const char *file, uint32_t file_len,
45  const char *status, uint32_t status_len);
46 
47 /* Possible flags of a StorageEngine (there can be 32 of them) */
48 enum engine_flag_bits {
49  HTON_BIT_ALTER_NOT_SUPPORTED, // Engine does not support alter
50  HTON_BIT_HIDDEN, // Engine does not appear in lists
51  HTON_BIT_NOT_USER_SELECTABLE,
52  HTON_BIT_TEMPORARY_NOT_SUPPORTED, // Having temporary tables not supported
53  HTON_BIT_TEMPORARY_ONLY,
54  HTON_BIT_DOES_TRANSACTIONS,
55  HTON_BIT_STATS_RECORDS_IS_EXACT,
56  HTON_BIT_NULL_IN_KEY,
57  HTON_BIT_CAN_INDEX_BLOBS,
58  HTON_BIT_PRIMARY_KEY_IN_READ_INDEX,
59  HTON_BIT_PARTIAL_COLUMN_READ,
60  HTON_BIT_TABLE_SCAN_ON_INDEX,
61  HTON_BIT_FAST_KEY_READ,
62  HTON_BIT_NO_BLOBS,
63  HTON_BIT_HAS_RECORDS,
64  HTON_BIT_NO_AUTO_INCREMENT,
65  HTON_BIT_DUPLICATE_POS,
66  HTON_BIT_AUTO_PART_KEY,
67  HTON_BIT_REQUIRE_PRIMARY_KEY,
68  HTON_BIT_REQUIRES_KEY_COLUMNS_FOR_DELETE,
69  HTON_BIT_PRIMARY_KEY_REQUIRED_FOR_DELETE,
70  HTON_BIT_NO_PREFIX_CHAR_KEYS,
71  HTON_BIT_HAS_CHECKSUM,
72  HTON_BIT_SKIP_STORE_LOCK,
73  HTON_BIT_SCHEMA_DICTIONARY,
74  HTON_BIT_FOREIGN_KEYS,
75  HTON_BIT_SIZE
76 };
77 
78 static const std::bitset<HTON_BIT_SIZE> HTON_NO_FLAGS(0);
79 static const std::bitset<HTON_BIT_SIZE> HTON_ALTER_NOT_SUPPORTED(1 << HTON_BIT_ALTER_NOT_SUPPORTED);
80 static const std::bitset<HTON_BIT_SIZE> HTON_HIDDEN(1 << HTON_BIT_HIDDEN);
81 static const std::bitset<HTON_BIT_SIZE> HTON_NOT_USER_SELECTABLE(1 << HTON_BIT_NOT_USER_SELECTABLE);
82 static const std::bitset<HTON_BIT_SIZE> HTON_TEMPORARY_NOT_SUPPORTED(1 << HTON_BIT_TEMPORARY_NOT_SUPPORTED);
83 static const std::bitset<HTON_BIT_SIZE> HTON_TEMPORARY_ONLY(1 << HTON_BIT_TEMPORARY_ONLY);
84 static const std::bitset<HTON_BIT_SIZE> HTON_HAS_DOES_TRANSACTIONS(1 << HTON_BIT_DOES_TRANSACTIONS);
85 static const std::bitset<HTON_BIT_SIZE> HTON_STATS_RECORDS_IS_EXACT(1 << HTON_BIT_STATS_RECORDS_IS_EXACT);
86 static const std::bitset<HTON_BIT_SIZE> HTON_NULL_IN_KEY(1 << HTON_BIT_NULL_IN_KEY);
87 static const std::bitset<HTON_BIT_SIZE> HTON_CAN_INDEX_BLOBS(1 << HTON_BIT_CAN_INDEX_BLOBS);
88 static const std::bitset<HTON_BIT_SIZE> HTON_PRIMARY_KEY_IN_READ_INDEX(1 << HTON_BIT_PRIMARY_KEY_IN_READ_INDEX);
89 static const std::bitset<HTON_BIT_SIZE> HTON_PARTIAL_COLUMN_READ(1 << HTON_BIT_PARTIAL_COLUMN_READ);
90 static const std::bitset<HTON_BIT_SIZE> HTON_TABLE_SCAN_ON_INDEX(1 << HTON_BIT_TABLE_SCAN_ON_INDEX);
91 static const std::bitset<HTON_BIT_SIZE> HTON_FAST_KEY_READ(1 << HTON_BIT_FAST_KEY_READ);
92 static const std::bitset<HTON_BIT_SIZE> HTON_NO_BLOBS(1 << HTON_BIT_NO_BLOBS);
93 static const std::bitset<HTON_BIT_SIZE> HTON_HAS_RECORDS(1 << HTON_BIT_HAS_RECORDS);
94 static const std::bitset<HTON_BIT_SIZE> HTON_NO_AUTO_INCREMENT(1 << HTON_BIT_NO_AUTO_INCREMENT);
95 static const std::bitset<HTON_BIT_SIZE> HTON_DUPLICATE_POS(1 << HTON_BIT_DUPLICATE_POS);
96 static const std::bitset<HTON_BIT_SIZE> HTON_AUTO_PART_KEY(1 << HTON_BIT_AUTO_PART_KEY);
97 static const std::bitset<HTON_BIT_SIZE> HTON_REQUIRE_PRIMARY_KEY(1 << HTON_BIT_REQUIRE_PRIMARY_KEY);
98 static const std::bitset<HTON_BIT_SIZE> HTON_REQUIRES_KEY_COLUMNS_FOR_DELETE(1 << HTON_BIT_REQUIRES_KEY_COLUMNS_FOR_DELETE);
99 static const std::bitset<HTON_BIT_SIZE> HTON_PRIMARY_KEY_REQUIRED_FOR_DELETE(1 << HTON_BIT_PRIMARY_KEY_REQUIRED_FOR_DELETE);
100 static const std::bitset<HTON_BIT_SIZE> HTON_NO_PREFIX_CHAR_KEYS(1 << HTON_BIT_NO_PREFIX_CHAR_KEYS);
101 static const std::bitset<HTON_BIT_SIZE> HTON_HAS_CHECKSUM(1 << HTON_BIT_HAS_CHECKSUM);
102 static const std::bitset<HTON_BIT_SIZE> HTON_SKIP_STORE_LOCK(1 << HTON_BIT_SKIP_STORE_LOCK);
103 static const std::bitset<HTON_BIT_SIZE> HTON_HAS_SCHEMA_DICTIONARY(1 << HTON_BIT_SCHEMA_DICTIONARY);
104 static const std::bitset<HTON_BIT_SIZE> HTON_HAS_FOREIGN_KEYS(1 << HTON_BIT_FOREIGN_KEYS);
105 
106 
107 namespace plugin {
108 
109 typedef std::vector<StorageEngine *> EngineVector;
110 
111 typedef std::set<std::string> TableNameList;
112 
113 extern const std::string UNKNOWN_STRING;
114 extern DRIZZLED_API const std::string DEFAULT_DEFINITION_FILE_EXT;
115 
116 
117 /*
118  StorageEngine is a singleton structure - one instance per storage engine -
119  to provide access to storage engine functionality that works on the
120  "global" level (unlike Cursor class that works on a per-table basis)
121 
122  usually StorageEngine instance is defined statically in ha_xxx.cc as
123 
124  static StorageEngine { ... } xxx_engine;
125 */
127  public Plugin,
129 {
130  friend class SEAPITester;
131 public:
132  typedef uint64_t Table_flags;
133 
134 private:
135  static EngineVector &getSchemaEngines();
136  const std::bitset<HTON_BIT_SIZE> flags; /* global Cursor flags */
137 
138 
139  virtual void setTransactionReadWrite(Session& session);
140 
141  /*
142  * Indicates to a storage engine the start of a
143  * new SQL statement.
144  */
145  virtual void doStartStatement(Session *session)
146  {
147  (void) session;
148  }
149 
150  /*
151  * Indicates to a storage engine the end of
152  * the current SQL statement in the supplied
153  * Session.
154  */
155  virtual void doEndStatement(Session *session)
156  {
157  (void) session;
158  }
159 
160 protected:
161  std::string table_definition_ext;
162 
163 public:
164  const std::string& getTableDefinitionFileExtension()
165  {
166  return table_definition_ext;
167  }
168 
169  virtual message::Table::Index::IndexType default_index_type() const
170  {
171  return message::Table::Index::BTREE;
172  }
173 
174 private:
175  std::vector<std::string> aliases;
176 
177 public:
178  const std::vector<std::string>& getAliases() const
179  {
180  return aliases;
181  }
182 
183  void addAlias(std::string alias)
184  {
185  aliases.push_back(alias);
186  }
187 
188 protected:
189 
194  typedef std::map <std::string, message::Table> ProtoCache;
195  ProtoCache proto_cache;
196  pthread_mutex_t proto_cache_mutex;
197 
198 public:
199  StorageEngine(const std::string &name_arg,
200  const std::bitset<HTON_BIT_SIZE> &flags_arg= HTON_NO_FLAGS);
201 
202  virtual ~StorageEngine();
203 
204 protected:
205  virtual int doGetTableDefinition(Session &session,
206  const drizzled::identifier::Table &identifier,
207  message::Table &table_message)
208  {
209  (void)session;
210  (void)identifier;
211  (void)table_message;
212 
213  return ENOENT;
214  }
215 
216  /* Old style cursor errors */
217  void print_keydup_error(uint32_t key_nr, const char *msg, const Table &table) const;
218  virtual bool get_error_message(int error, String *buf) const;
219 
220 public:
221  virtual void print_error(int error, myf errflag, const Table& table) const;
222 
223  bool is_user_selectable() const
224  {
225  return not flags.test(HTON_BIT_NOT_USER_SELECTABLE);
226  }
227 
228  bool check_flag(const engine_flag_bits flag) const
229  {
230  return flags.test(flag);
231  }
232 
233  // @todo match check_flag interface
234  virtual uint32_t index_flags(enum ha_key_alg) const { return 0; }
235  virtual void startStatement(Session *session)
236  {
237  doStartStatement(session);
238  }
239  virtual void endStatement(Session *session)
240  {
241  doEndStatement(session);
242  }
243 
244  /*
245  * Called during Session::cleanup() for all engines
246  */
247  virtual int close_connection(Session *)
248  {
249  return 0;
250  }
251 
252  virtual Cursor *create(Table &)= 0;
253  /* args: path */
254  virtual bool flush_logs() { return false; }
255  virtual bool show_status(Session *, stat_print_fn *, enum ha_stat_type)
256  {
257  return false;
258  }
259 
271  virtual const char **bas_ext() const =0;
272 
273 protected:
274  virtual int doCreateTable(Session &session,
275  Table &table_arg,
276  const drizzled::identifier::Table &identifier,
277  const message::Table &message)= 0;
278 
279  virtual int doRenameTable(Session &session,
280  const drizzled::identifier::Table &from, const drizzled::identifier::Table &to)= 0;
281 
282  virtual int doDropTable(Session &session,
283  const drizzled::identifier::Table &identifier)= 0;
284 
285  virtual void doGetTableIdentifiers(CachedDirectory &directory,
286  const drizzled::identifier::Schema &schema_identifier,
287  identifier::table::vector &set_of_identifiers)= 0;
288 
289  virtual bool doDoesTableExist(Session& session, const drizzled::identifier::Table &identifier);
290 
291  virtual bool doCanCreateTable(const drizzled::identifier::Table &identifier)
292  { (void)identifier; return true; }
293 
294 public:
295 
296  friend class AddSchemaNames;
297  friend class AddTableIdentifier;
298  friend class AlterSchema;
299  friend class CanCreateTable;
300  friend class CreateSchema;
301  friend class DropSchema;
302  friend class DropTable;
303  friend class DropTables;
304  friend class FindEngineByName;
305  friend class Ha_delete_table_error_handler;
306  friend class StorageEngineCloseConnection;
307  friend class StorageEngineDoesTableExist;
308  friend class StorageEngineGetSchemaDefinition;
309  friend class StorageEngineGetTableDefinition;
310  friend class DropTableByIdentifier;
311 
312  int renameTable(Session &session, const drizzled::identifier::Table &from, const drizzled::identifier::Table &to);
313 
314  /* Class Methods for operating on plugin */
315  static bool addPlugin(plugin::StorageEngine *engine);
316  static void removePlugin(plugin::StorageEngine *engine);
317 
318  static message::table::shared_ptr getTableMessage(Session& session,
319  const drizzled::identifier::Table &identifier,
320  bool include_temporary_tables= true);
321  static bool doesTableExist(Session &session,
322  const drizzled::identifier::Table &identifier,
323  bool include_temporary_tables= true);
324 
325  static plugin::StorageEngine *findByName(const std::string &find_str);
326  static plugin::StorageEngine *findByName(Session& session, const std::string &find_str);
327 
328  static void closeConnection(Session&);
329  static void dropDatabase(char* path);
330  static bool flushLogs(plugin::StorageEngine *db_type);
331 
332  static bool dropTable(Session& session,
333  const drizzled::identifier::Table &identifier);
334  static bool dropTable(Session& session,
335  const drizzled::identifier::Table &identifier,
336  drizzled::error_t &error);
337 
338  static bool dropTable(Session& session,
339  StorageEngine &engine,
340  const identifier::Table& identifier,
341  drizzled::error_t &error);
342 
343  static void getIdentifiers(Session &session,
344  const identifier::Schema &schema_identifier,
345  identifier::table::vector &set_of_identifiers);
346 
347  // Check to see if any SE objects to creation.
348  static bool canCreateTable(const drizzled::identifier::Table &identifier);
349 
350  // @note All schema methods defined here
351  static void getIdentifiers(Session &session, identifier::schema::vector &schemas);
352  static message::schema::shared_ptr getSchemaDefinition(const drizzled::identifier::Table &identifier);
353  static message::schema::shared_ptr getSchemaDefinition(const drizzled::identifier::Schema &identifier);
354  static bool doesSchemaExist(const drizzled::identifier::Schema &identifier);
355  static const charset_info_st *getSchemaCollation(const drizzled::identifier::Schema &identifier);
356  static bool createSchema(const drizzled::message::Schema &schema_message);
357  static bool dropSchema(Session &session,
358  const identifier::Schema& identifier,
359  message::schema::const_reference schema_message);
360  static bool alterSchema(const drizzled::message::Schema &schema_message);
361 
362  // @note make private/protected
363 protected:
364  virtual void doGetSchemaIdentifiers(identifier::schema::vector&)
365  { }
366 
367  virtual drizzled::message::schema::shared_ptr doGetSchemaDefinition(const drizzled::identifier::Schema&)
368  {
369  return drizzled::message::schema::shared_ptr();
370  }
371 
372  virtual bool doCreateSchema(const drizzled::message::Schema&)
373  { return false; }
374 
375  virtual bool doAlterSchema(const drizzled::message::Schema&)
376  { return false; }
377 
378  virtual bool doDropSchema(const drizzled::identifier::Schema&)
379  { return false; }
380 
381 public:
382  static inline const std::string &resolveName(const StorageEngine *engine)
383  {
384  return engine == NULL ? UNKNOWN_STRING : engine->getName();
385  }
386 
387  static bool createTable(Session &session,
388  const identifier::Table &identifier,
389  message::Table& table_message);
390 
391  static void removeLostTemporaryTables(Session &session, const char *directory);
392 
393  Cursor *getCursor(Table &share);
394 
395  uint32_t max_record_length() const
396  { return std::min(HA_MAX_REC_LENGTH, max_supported_record_length()); }
397  uint32_t max_keys() const
398  { return std::min(MAX_KEY, max_supported_keys()); }
399  uint32_t max_key_parts() const
400  { return std::min(MAX_REF_PARTS, max_supported_key_parts()); }
401  uint32_t max_key_length() const
402  { return std::min(MAX_KEY_LENGTH, max_supported_key_length()); }
403  uint32_t max_key_part_length(void) const
404  { return std::min(MAX_KEY_LENGTH, max_supported_key_part_length()); }
405 
406  virtual uint32_t max_supported_record_length(void) const
407  { return HA_MAX_REC_LENGTH; }
408  virtual uint32_t max_supported_keys(void) const { return 0; }
409  virtual uint32_t max_supported_key_parts(void) const { return MAX_REF_PARTS; }
410  virtual uint32_t max_supported_key_length(void) const { return MAX_KEY_LENGTH; }
411  virtual uint32_t max_supported_key_part_length(void) const { return 255; }
412 
413  /* TODO-> Make private */
414 protected:
415  static int deleteDefinitionFromPath(const drizzled::identifier::Table &identifier);
416  static int renameDefinitionFromPath(const drizzled::identifier::Table &dest, const drizzled::identifier::Table &src);
417  static int writeDefinitionFromPath(const drizzled::identifier::Table &identifier, const message::Table &proto);
418  static bool readTableFile(const std::string &path, message::Table &table_message);
419 
420 public:
421  /*
422  * The below are simple virtual overrides for the plugin::MonitoredInTransaction
423  * interface.
424  */
425  virtual bool participatesInSqlTransaction() const
426  {
427  return false; /* plugin::StorageEngine is non-transactional in terms of SQL */
428  }
429  virtual bool participatesInXaTransaction() const
430  {
431  return false; /* plugin::StorageEngine is non-transactional in terms of XA */
432  }
433  virtual bool alwaysRegisterForXaTransaction() const
434  {
435  return false;
436  }
437 
438  virtual bool validateCreateTableOption(const std::string &key, const std::string &state)
439  {
440  (void)key;
441  (void)state;
442 
443  return false;
444  }
445 
446  virtual bool validateCreateSchemaOption(const std::string &key, const std::string &state)
447  {
448  (void)key;
449  (void)state;
450 
451  return false;
452  }
453 };
454 
455 std::ostream& operator<<(std::ostream& output, const StorageEngine &engine);
456 
457 } /* namespace plugin */
458 } /* namespace drizzled */
459 
virtual bool participatesInXaTransaction() const
virtual bool alwaysRegisterForXaTransaction() const
#define DRIZZLED_API
Definition: visibility.h:62
std::map< std::string, message::Table > ProtoCache
Used as a protobuf storage currently by TEMP only engines.
Visibility Control Macros.
virtual bool participatesInSqlTransaction() const