1/*****************************************************************************
2
3Copyright (c) 2007, 2016, Oracle and/or its affiliates. All Rights Reserved.
4
5This program is free software; you can redistribute it and/or modify it under
6the terms of the GNU General Public License as published by the Free Software
7Foundation; version 2 of the License.
8
9This program is distributed in the hope that it will be useful, but WITHOUT
10ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
12
13You should have received a copy of the GNU General Public License along with
14this program; if not, write to the Free Software Foundation, Inc.,
1551 Franklin Street, Suite 500, Boston, MA 02110-1335 USA
16
17*****************************************************************************/
18
19/**************************************************//**
20@file include/ha0storage.h
21Hash storage.
22Provides a data structure that stores chunks of data in
23its own storage, avoiding duplicates.
24
25Created September 22, 2007 Vasil Dimov
26*******************************************************/
27
28#ifndef ha0storage_h
29#define ha0storage_h
30
31#include "univ.i"
32
33/** This value is used by default by ha_storage_create(). More memory
34is allocated later when/if it is needed. */
35#define HA_STORAGE_DEFAULT_HEAP_BYTES 1024
36
37/** This value is used by default by ha_storage_create(). It is a
38constant per ha_storage's lifetime. */
39#define HA_STORAGE_DEFAULT_HASH_CELLS 4096
40
41/** Hash storage */
42struct ha_storage_t;
43
44/*******************************************************************//**
45Creates a hash storage. If any of the parameters is 0, then a default
46value is used.
47@return own: hash storage */
48UNIV_INLINE
49ha_storage_t*
50ha_storage_create(
51/*==============*/
52 ulint initial_heap_bytes, /*!< in: initial heap's size */
53 ulint initial_hash_cells); /*!< in: initial number of cells
54 in the hash table */
55
56/*******************************************************************//**
57Copies data into the storage and returns a pointer to the copy. If the
58same data chunk is already present, then pointer to it is returned.
59Data chunks are considered to be equal if len1 == len2 and
60memcmp(data1, data2, len1) == 0. If "data" is not present (and thus
61data_len bytes need to be allocated) and the size of storage is going to
62become more than "memlim" then "data" is not added and NULL is returned.
63To disable this behavior "memlim" can be set to 0, which stands for
64"no limit".
65@return pointer to the copy */
66const void*
67ha_storage_put_memlim(
68/*==================*/
69 ha_storage_t* storage, /*!< in/out: hash storage */
70 const void* data, /*!< in: data to store */
71 ulint data_len, /*!< in: data length */
72 ulint memlim); /*!< in: memory limit to obey */
73
74/*******************************************************************//**
75Same as ha_storage_put_memlim() but without memory limit.
76@param storage in/out: hash storage
77@param data in: data to store
78@param data_len in: data length
79@return pointer to the copy of the string */
80#define ha_storage_put(storage, data, data_len) \
81 ha_storage_put_memlim((storage), (data), (data_len), 0)
82
83/*******************************************************************//**
84Copies string into the storage and returns a pointer to the copy. If the
85same string is already present, then pointer to it is returned.
86Strings are considered to be equal if strcmp(str1, str2) == 0.
87@param storage in/out: hash storage
88@param str in: string to put
89@return pointer to the copy of the string */
90#define ha_storage_put_str(storage, str) \
91 ((const char*) ha_storage_put((storage), (str), strlen(str) + 1))
92
93/*******************************************************************//**
94Copies string into the storage and returns a pointer to the copy obeying
95a memory limit.
96If the same string is already present, then pointer to it is returned.
97Strings are considered to be equal if strcmp(str1, str2) == 0.
98@param storage in/out: hash storage
99@param str in: string to put
100@param memlim in: memory limit to obey
101@return pointer to the copy of the string */
102#define ha_storage_put_str_memlim(storage, str, memlim) \
103 ((const char*) ha_storage_put_memlim((storage), (str), \
104 strlen(str) + 1, (memlim)))
105
106/*******************************************************************//**
107Empties a hash storage, freeing memory occupied by data chunks.
108This invalidates any pointers previously returned by ha_storage_put().
109The hash storage is not invalidated itself and can be used again. */
110UNIV_INLINE
111void
112ha_storage_empty(
113/*=============*/
114 ha_storage_t** storage); /*!< in/out: hash storage */
115
116/*******************************************************************//**
117Frees a hash storage and everything it contains, it cannot be used after
118this call.
119This invalidates any pointers previously returned by ha_storage_put(). */
120UNIV_INLINE
121void
122ha_storage_free(
123/*============*/
124 ha_storage_t* storage); /*!< in, own: hash storage */
125
126/*******************************************************************//**
127Gets the size of the memory used by a storage.
128@return bytes used */
129UNIV_INLINE
130ulint
131ha_storage_get_size(
132/*================*/
133 const ha_storage_t* storage); /*!< in: hash storage */
134
135#include "ha0storage.ic"
136
137#endif /* ha0storage_h */
138