|
18 | 18 | //! There are two major APIs: |
19 | 19 | //! - [`craw`], the FFI bindings generated directly by bindgen. |
20 | 20 | //! These are not recommended for normal use, |
21 | | -//! but are available in case the `context_api` is missing functionality. |
22 | | -//! - [`context_api`], which is a safe wrapper around the C API which |
23 | | -//! stores the current tptoken and an error buffer |
24 | | -//! so you don't have to keep track of them yourself. |
25 | | -//! The reason this metadata is necessary is because this crate binds to |
26 | | -//! the threaded version of YottaDB, which requires a `tptoken` and `err_buffer`. |
27 | | -//! See [transaction processing] for more details on transactions and `tptoken`s. |
28 | | -//! |
29 | | -//! Most operations are encapsulated in methods in the [KeyContext] struct. |
| 21 | +//! but are available in case the Context API is missing functionality. |
| 22 | +//! - The main Context API, which is a safe wrapper around the C API which |
| 23 | +//! stores the current tptoken and an error buffer so you don't have to keep track of them yourself. |
| 24 | +//! The reason this metadata is necessary is because this crate binds to the threaded version of |
| 25 | +//! YottaDB, which requires a `tptoken` and `err_buffer`. See [transaction processing] for more |
| 26 | +//! details on transactions and `tptoken`s. |
| 27 | +//! |
| 28 | +//! Most operations are encapsulated in methods in the [`KeyContext`] struct. |
30 | 29 | //! Iteration helpers are available to iterate over values in the database in a variety of ways. |
31 | 30 | //! |
32 | 31 | //! # Examples |
|
47 | 46 | //! } |
48 | 47 | //! ``` |
49 | 48 | //! |
| 49 | +//! # Intrinsic Variables |
| 50 | +//! |
| 51 | +//! YottaDB has several intrinsic variables which are documented [online][intrinsics]. |
| 52 | +//! To get the value of these variables, call `get_st` on a `Key` with the name of the variable. |
| 53 | +//! |
| 54 | +//! ## Example |
| 55 | +//! |
50 | 56 | //! Get the instrinsic variable [`$tlevel`][tlevel], which gives the current transaction level. |
51 | 57 | //! |
52 | 58 | //! ``` |
|
62 | 68 | //! } |
63 | 69 | //! ``` |
64 | 70 | //! |
65 | | -//! # Intrinsic Variables |
66 | | -//! |
67 | | -//! YottaDB has several intrinsic variables which are documented [online][intrinsics]. |
68 | | -//! To get the value of these variables, call `get_st` on a `Key` with the name of the variable. |
69 | | -//! |
70 | | -//! ## Features |
| 71 | +//! # Features |
71 | 72 | //! |
72 | 73 | //! Since `yottadb` is a set of bindings to a C library, it uses `bindgen` to generate the bindings. |
73 | 74 | //! There are two ways to do this: |
|
78 | 79 | //! even when you don't have admin priviledges to install programs. |
79 | 80 | //! Using a pre-installed version means compile times are much lower. |
80 | 81 | //! |
81 | | -//! ## Signal handling |
| 82 | +//! # Signal handling |
82 | 83 | //! |
83 | 84 | //! YottaDB performs its own signal handling in addition to any signal handlers you may have set up. |
84 | 85 | //! Since many functions in C are not async-safe, it defers any action until the next time `ydb_eintr_handler` is called. |
85 | 86 | //! All YDB functions will automatically call `ydb_eintr_handler` if necessary, |
86 | 87 | //! so in most cases this should not affect your application. However, there are some rare cases |
87 | 88 | //! when the handler will not be called: |
88 | | -//! - If you have a tight loop inside a [`tp`] that does not call a YDB function |
| 89 | +//! - If you have a tight loop inside a [`Context::tp`] that does not call a YDB function |
89 | 90 | //! |
90 | 91 | //! For example, the following loop will run forever even if sent SIGINT: |
91 | 92 | //! ```no_run |
|
101 | 102 | //! # } |
102 | 103 | //! ``` |
103 | 104 | //! |
104 | | -//! To avoid this, call [`eintr_handler`] in the loop: |
| 105 | +//! To avoid this, call [`Context::eintr_handler`] in the loop: |
105 | 106 | //! |
106 | 107 | //! ```no_run |
107 | 108 | //! # fn main() -> yottadb::YDBResult<()> { |
|
126 | 127 | //! YottaDB does not register any signal handlers until the first time `ydb_init` is called, |
127 | 128 | //! and deregisters its handlers after `ydb_exit`. |
128 | 129 | //! |
129 | | -//! ### See also |
| 130 | +//! ## See also |
130 | 131 | //! |
131 | 132 | //! - The [C documentation on signals](https://docs.yottadb.com/MultiLangProgGuide/programmingnotes.html#signals) |
132 | | -//! - [`eintr_handler`] |
133 | | -//! - [`eintr_handler_t`] |
134 | | -//! - [`tp`] |
135 | | -//! |
136 | | -//! [`YDBError`]: simple_api::YDBError |
137 | | -//! [`eintr_handler`]: context_api::Context::eintr_handler() |
138 | | -//! [`eintr_handler_t`]: simple_api::eintr_handler_t() |
139 | | -//! [`tp`]: context_api::Context::tp() |
| 133 | +//! - [`Context::eintr_handler`] |
| 134 | +//! - [`Context::tp`](crate::Context::tp) |
| 135 | +//! |
140 | 136 | //! [YottaDB]: https://yottadb.com/ |
141 | 137 | //! [transaction processing]: https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#transaction-processing |
142 | | -//! [key]: Key |
143 | 138 | //! [intrinsics]: https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#intrinsic-special-variables |
144 | 139 | //! [tlevel]: https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#tlevel |
145 | 140 | #![deny(missing_docs)] |
|
153 | 148 | #[allow(unused)] |
154 | 149 | const INTERNAL_DOCS: () = (); |
155 | 150 |
|
156 | | -// Public to reduce churn when upgrading versions, but it's recommended to use the top-level re-exports instead. |
| 151 | +/// Public to reduce churn when upgrading versions, but it's recommended to use the top-level re-exports instead. |
157 | 152 | #[doc(hidden)] |
158 | | -pub mod context_api; |
| 153 | +mod context_api; |
159 | 154 | #[allow(missing_docs)] |
160 | 155 | pub mod craw; |
161 | 156 | mod simple_api; |
162 | 157 |
|
163 | 158 | pub use craw::{YDB_ERR_GVUNDEF, YDB_ERR_LVUNDEF}; |
| 159 | +#[doc(inline)] // needed because of rust-lang/rust#81890 |
164 | 160 | pub use context_api::*; // glob import so we catch all the iterators |
165 | 161 | pub use simple_api::{ |
166 | 162 | call_in::{CallInDescriptor, CallInTableDescriptor}, |
|
0 commit comments