xref: /6.0.3/forestdb/src/docio.h (revision cc8ad991)
1/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
2/*
3 *     Copyright 2010 Couchbase, Inc
4 *
5 *   Licensed under the Apache License, Version 2.0 (the "License");
6 *   you may not use this file except in compliance with the License.
7 *   You may obtain a copy of the License at
8 *
9 *       http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *   Unless required by applicable law or agreed to in writing, software
12 *   distributed under the License is distributed on an "AS IS" BASIS,
13 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *   See the License for the specific language governing permissions and
15 *   limitations under the License.
16 */
17
18#ifndef _JSAHN_DOCIO_H
19#define _JSAHN_DOCIO_H
20
21#include "filemgr.h"
22#include "common.h"
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28typedef uint16_t keylen_t;
29typedef uint32_t timestamp_t;
30
31struct docio_handle {
32    struct filemgr *file;
33    bid_t curblock;
34    uint32_t curpos;
35    uint16_t cur_bmp_revnum_hash;
36    // for buffer purpose
37    bid_t lastbid;
38    uint64_t lastBmpRevnum;
39    void *readbuffer;
40    err_log_callback *log_callback;
41    bool compress_document_body;
42};
43
44#define DOCIO_NORMAL (0x00)
45#define DOCIO_COMPACT (0x01)
46#define DOCIO_COMPRESSED (0x02)
47#define DOCIO_DELETED (0x04)
48#define DOCIO_TXN_DIRTY (0x08)
49#define DOCIO_TXN_COMMITTED (0x10)
50#define DOCIO_SYSTEM (0x20) /* system document */
51#ifdef DOCIO_LEN_STRUCT_ALIGN
52    // this structure will occupy 16 bytes
53    struct docio_length {
54        keylen_t keylen;
55        uint16_t metalen;
56        uint32_t bodylen;
57        uint32_t bodylen_ondisk;
58        uint8_t flag;
59        uint8_t checksum;
60    };
61#else
62    // this structure will occupy 14 bytes
63    struct __attribute__ ((packed)) docio_length {
64        keylen_t keylen;
65        uint16_t metalen;
66        uint32_t bodylen;
67        uint32_t bodylen_ondisk;
68        uint8_t flag;
69        uint8_t checksum;
70    };
71#endif
72
73struct docio_object {
74    struct docio_length length;
75    timestamp_t timestamp;
76    void *key;
77    union {
78        fdb_seqnum_t seqnum;
79        uint64_t doc_offset;
80    };
81    void *meta;
82    void *body;
83};
84
85fdb_status docio_init(struct docio_handle *handle,
86                      struct filemgr *file,
87                      bool compress_document_body);
88void docio_free(struct docio_handle *handle);
89
90bid_t docio_append_doc_raw(struct docio_handle *handle,
91                           uint64_t size,
92                           void *buf);
93
94#define DOCIO_COMMIT_MARK_SIZE (sizeof(struct docio_length) + sizeof(uint64_t))
95bid_t docio_append_commit_mark(struct docio_handle *handle, uint64_t doc_offset);
96bid_t docio_append_doc(struct docio_handle *handle, struct docio_object *doc,
97                       uint8_t deleted, uint8_t txn_enabled);
98bid_t docio_append_doc_system(struct docio_handle *handle, struct docio_object *doc);
99
100/**
101 * Retrieve the length info of a KV item at a given file offset.
102 *
103 * @param handle Pointer to the doc I/O handle
104 * @Param length Pointer to docio_length instance to be populated
105 * @param offset File offset to a KV item
106 * @return FDB_RESULT_SUCCESS on success
107 */
108fdb_status docio_read_doc_length(struct docio_handle *handle,
109                                 struct docio_length *length,
110                                 uint64_t offset);
111
112/**
113 * Read a key and its length at a given file offset.
114 *
115 * @param handle Pointer to the doc I/O handle
116 * @param offset File offset to a KV item
117 * @param keylen Pointer to a key length variable
118 * @param keybuf Pointer to a key buffer
119 * @return FDB_RESULT_SUCCESS on success
120 */
121fdb_status docio_read_doc_key(struct docio_handle *handle,
122                              uint64_t offset,
123                              keylen_t *keylen,
124                              void *keybuf);
125
126/**
127 * Read a key and its metadata at a given file offset.
128 *
129 * @param handle Pointer to the doc I/O handle
130 * @param offset File offset to a KV item
131 * @param doc Pointer to docio_object instance
132 * @param read_on_cache_miss Flag indicating if a disk read should be performed
133 *        on cache miss
134 * @return next offset right after a key and its metadata on succcessful read,
135 *         otherwise, the corresponding error code is returned.
136 */
137int64_t docio_read_doc_key_meta(struct docio_handle *handle,
138                                uint64_t offset,
139                                struct docio_object *doc,
140                                bool read_on_cache_miss);
141
142/**
143 * Read a KV item at a given file offset.
144 *
145 * @param handle Pointer to the doc I/O handle
146 * @param offset File offset to a KV item
147 * @param doc Pointer to docio_object instance
148 * @param read_on_cache_miss Flag indicating if a disk read should be performed
149 *        on cache miss
150 * @return next offset right after a key and its value on succcessful read,
151 *         otherwise, the corresponding error code is returned.
152 */
153int64_t docio_read_doc(struct docio_handle *handle,
154                       uint64_t offset,
155                       struct docio_object *doc,
156                       bool read_on_cache_miss);
157
158size_t docio_batch_read_docs(struct docio_handle *handle,
159                             uint64_t *offset_array,
160                             struct docio_object *doc_array,
161                             size_t array_size,
162                             size_t data_size_threshold,
163                             size_t batch_size_threshold,
164                             struct async_io_handle *aio_handle,
165                             bool keymeta_only);
166
167/**
168 * Check if the given block is a valid document block. The bitmap revision number of
169 * the document block should match the passed revision number.
170 *
171 * @param handle Pointer to DocIO handle.
172 * @param bid ID of the block.
173 * @param sb_bmp_revnum Revision number of bitmap in superblock. If the value is
174 *        -1, this function does not care about revision number.
175 * @return True if valid.
176 */
177bool docio_check_buffer(struct docio_handle *handle,
178                        bid_t bid,
179                        uint64_t sb_bmp_revnum);
180
181
182INLINE void docio_reset(struct docio_handle *dhandle) {
183    dhandle->curblock = BLK_NOT_FOUND;
184}
185void free_docio_object(struct docio_object *doc, uint8_t key_alloc,
186                       uint8_t meta_alloc, uint8_t body_alloc);
187
188#ifdef __cplusplus
189}
190#endif
191
192#endif
193