Skip to content

Commit

Permalink
docs: Add the "Crate Features" section
Browse files Browse the repository at this point in the history
  • Loading branch information
@blackbeam
blackbeam committed Dec 29, 2021
1 parent 09c3b62 commit 1edd17e
Show file tree
Hide file tree
Showing 5 changed files with 103 additions and 146 deletions.
5 changes: 5 additions & 0 deletions Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,18 @@ default = [
# It is necessary to choose one of `flate2` backends.
"flate2/zlib",

# set of enabled-by-default mysql_common features
"mysql_common/bigdecimal03",
"mysql_common/rust_decimal",
"mysql_common/time03",
"mysql_common/uuid",
"mysql_common/frunk",

# use global buffer pool by default
"buffer-pool",
]
rustls-tls = ["rustls", "webpki", "webpki-roots", "rustls-pemfile"]
buffer-pool = []
nightly = []

[dev-dependencies]
Expand Down
61 changes: 45 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,44 @@ assert_eq!(payments, selected_payments);
println!("Yay!");
```

### Crate Features

* crate's features:

* **native-tls** (enabled by default) – specifies `native-tls` as the TLS backend
(see the [SSL Support](#ssl-support) section)
* **rustls-tls** (disabled by default) – specifies `rustls` as the TLS backend
(see the [SSL Support](#ssl-support) section)
* **buffer-pool** (enabled by default) – enables buffer pooling
(see the [Buffer Pool](#buffer-pool) section)

* external features enabled by default:

* for the `flate2` crate (please consult `flate2` crate documentation for available features):

* **flate2/zlib** (necessary) – `zlib` backend is chosed by default.

* for the `mysql_common` crate (please consult `mysql_common` crate documentation for available features):

* **mysql_common/bigdecimal03** – the `bigdecimal03` is enabled by default
* **mysql_common/rust_decimal** – the `rust_decimal` is enabled by default
* **mysql_common/time03** – the `time03` is enabled by default
* **mysql_common/uuid** – the `uuid` is enabled by default
* **mysql_common/frunk** – the `frunk` is enabled by default

Please note, that you'll need to reenable external features if you are using `no-default-features = true`:

```toml
[dependencies]
# Lets say that we want to use the `rustls-tls` feature:
mysql = { version = "*", no-default-features = true, features = ["rustls-tls", "buffer-pool"] }
# Previous line disables default mysql features,
# so now we have to choose the flate2 backend (this is necessary),
# as well as the desired set of mysql_common features:
flate2 = { version = "*", no-default-features = true, features = ["zlib"] }
mysql_common = { version = "*", no-default-features = true, features = ["bigdecimal03", "time03", "uuid"]}
```

### API Documentation

Please refer to the [crate docs].
Expand Down Expand Up @@ -637,15 +675,14 @@ that helps to avoid allocations for basic scenarios. You can control it's charac
the following environment variables:

* `RUST_MYSQL_BUFFER_POOL_CAP` (defaults to 128) – controls the pool capacity. Dropped buffer will
be immediately deallocated if the pool is full.

**Note:** it might be the case, that you don't need the pooling (say you are using jemalloc).
It's possible to disable the pool by setting the `RUST_MYSQL_BUFFER_POOL_CAP` environment
variable to `0`.
be immediately deallocated if the pool is full. Set it to `0` to disable the pool at runtime.

* `RUST_MYSQL_BUFFER_SIZE_CAP` (defaults to 4MiB) – controls the maximum capacity of a buffer
stored in the pool. Capacity of a dropped buffer will be shrinked to this value when buffer
is returning to the pool.
is returned to the pool.

To completely disable the pool (say you are using jemalloc) please remove the `buffer-pool` feature
from the set of default crate features (see the [Crate Features](#crate-features) section).

#### `BinQuery` and `BatchQuery` traits.

Expand Down Expand Up @@ -725,17 +762,9 @@ SSL support comes in two flavors:
1. Based on **native-tls** – this is the default option, that usually works without pitfalls
(see the `native-tls` crate feature).
2. Based on **rustls** – TLS backend written in Rust. Please use the `rustls-tls` crate feature
to enable:

```toml
[dependencies]
mysql = { version = "*", no-default-features = true, features = ["rustls-tls"] }
# Please note, that the previous line disables default mysql features,
# so now we have to choose the flate2 backend (this is necessary):
flate2 = { version = "1.0", no-default-features = true, features = ["zlib"] }
```
to enable it (see the [Crate Features](#crate-features) section).

Please also note a few things about this backend:
Please also note a few things about **rustls**:

* it will fail if you'll try to connect to the server by its IP address, hostname is required;
* it, most likely, won't work on windows, at least with default server certs, generated by the
Expand Down
101 changes: 0 additions & 101 deletions src/buffer_pool.rs
View file

This file was deleted.

16 changes: 8 additions & 8 deletions src/conn/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ use std::{
};

use crate::{
buffer_pool::PooledBuf,
buffer_pool::{get_buffer, Buffer},
conn::{
local_infile::LocalInfile,
pool::{Pool, PooledConn},
Expand Down Expand Up @@ -410,9 +410,9 @@ impl Conn {
Ok(())
}

fn read_packet(&mut self) -> Result<PooledBuf> {
fn read_packet(&mut self) -> Result<Buffer> {
loop {
let mut buffer = crate::BUFFER_POOL.get();
let mut buffer = get_buffer();
if !self.stream_mut().next_packet(buffer.as_mut())? {
return Err(
io::Error::new(io::ErrorKind::BrokenPipe, "server disconnected").into(),
Expand Down Expand Up @@ -441,7 +441,7 @@ impl Conn {
}

fn write_struct<T: MySerialize>(&mut self, s: &T) -> Result<()> {
let mut buf = crate::BUFFER_POOL.get();
let mut buf = get_buffer();
s.serialize(buf.as_mut());
self.write_packet(&mut &*buf)
}
Expand All @@ -462,7 +462,7 @@ impl Conn {

fn handle_ok<'a, T: OkPacketKind>(
&mut self,
buffer: &'a PooledBuf,
buffer: &'a Buffer,
) -> crate::Result<OkPacket<'a>> {
let ok = ParseBuf(&**buffer)
.parse::<OkPacketDeserializer<T>>(self.0.capability_flags)?
Expand Down Expand Up @@ -652,7 +652,7 @@ impl Conn {
Some(self.connect_attrs().clone()),
);

let mut buf = crate::BUFFER_POOL.get();
let mut buf = get_buffer();
handshake_response.serialize(buf.as_mut());
self.write_packet(&mut &*buf)
}
Expand Down Expand Up @@ -771,7 +771,7 @@ impl Conn {
}

fn write_command_raw<T: MySerialize>(&mut self, cmd: &T) -> Result<()> {
let mut buf = crate::BUFFER_POOL.get();
let mut buf = get_buffer();
cmd.serialize(buf.as_mut());
self.reset_seq_id();
debug_assert!(buf.len() > 0);
Expand All @@ -780,7 +780,7 @@ impl Conn {
}

fn write_command(&mut self, cmd: Command, data: &[u8]) -> Result<()> {
let mut buf = crate::BUFFER_POOL.get();
let mut buf = get_buffer();
buf.as_mut().put_u8(cmd as u8);
buf.as_mut().extend_from_slice(data);

Expand Down
66 changes: 45 additions & 21 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,44 @@
//! # });
//! ```
//!
//! ## Crate Features
//!
//! * crate's features:
//!
//! * **native-tls** (enabled by default) – specifies `native-tls` as the TLS backend
//! (see the [SSL Support](#ssl-support) section)
//! * **rustls-tls** (disabled by default) – specifies `rustls` as the TLS backend
//! (see the [SSL Support](#ssl-support) section)
//! * **buffer-pool** (enabled by default) – enables buffer pooling
//! (see the [Buffer Pool](#buffer-pool) section)
//!
//! * external features enabled by default:
//!
//! * for the `flate2` crate (please consult `flate2` crate documentation for available features):
//!
//! * **flate2/zlib** (necessary) – `zlib` backend is chosed by default.
//!
//! * for the `mysql_common` crate (please consult `mysql_common` crate documentation for available features):
//!
//! * **mysql_common/bigdecimal03** – the `bigdecimal03` is enabled by default
//! * **mysql_common/rust_decimal** – the `rust_decimal` is enabled by default
//! * **mysql_common/time03** – the `time03` is enabled by default
//! * **mysql_common/uuid** – the `uuid` is enabled by default
//! * **mysql_common/frunk** – the `frunk` is enabled by default
//!
//! Please note, that you'll need to reenable external features if you are using `no-default-features = true`:
//!
//! ```toml
//! [dependencies]
//! # Lets say that we want to use the `rustls-tls` feature:
//! mysql = { version = "*", no-default-features = true, features = ["rustls-tls", "buffer-pool"] }
//! # Previous line disables default mysql features,
//! # so now we have to choose the flate2 backend (this is necessary),
//! # as well as the desired set of mysql_common features:
//! flate2 = { version = "*", no-default-features = true, features = ["zlib"] }
//! mysql_common = { version = "*", no-default-features = true, features = ["bigdecimal03", "time03", "uuid"]}
//! ```
//!
//! ## API Documentation
//!
//! Please refer to the [crate docs].
Expand Down Expand Up @@ -684,15 +722,14 @@
//! the following environment variables:
//!
//! * `RUST_MYSQL_BUFFER_POOL_CAP` (defaults to 128) – controls the pool capacity. Dropped buffer will
//! be immediately deallocated if the pool is full.
//!
//! **Note:** it might be the case, that you don't need the pooling (say you are using jemalloc).
//! It's possible to disable the pool by setting the `RUST_MYSQL_BUFFER_POOL_CAP` environment
//! variable to `0`.
//! be immediately deallocated if the pool is full. Set it to `0` to disable the pool at runtime.
//!
//! * `RUST_MYSQL_BUFFER_SIZE_CAP` (defaults to 4MiB) – controls the maximum capacity of a buffer
//! stored in the pool. Capacity of a dropped buffer will be shrinked to this value when buffer
//! is returning to the pool.
//! is returned to the pool.
//!
//! To completely disable the pool (say you are using jemalloc) please remove the `buffer-pool` feature
//! from the set of default crate features (see the [Crate Features](#crate-features) section).
//!
//! ### `BinQuery` and `BatchQuery` traits.
//!
Expand Down Expand Up @@ -776,17 +813,9 @@
//! 1. Based on **native-tls** – this is the default option, that usually works without pitfalls
//! (see the `native-tls` crate feature).
//! 2. Based on **rustls** – TLS backend written in Rust. Please use the `rustls-tls` crate feature
//! to enable:
//!
//! ```toml
//! [dependencies]
//! mysql = { version = "*", no-default-features = true, features = ["rustls-tls"] }
//! # Please note, that the previous line disables default mysql features,
//! # so now we have to choose the flate2 backend (this is necessary):
//! flate2 = { version = "1.0", no-default-features = true, features = ["zlib"] }
//! ```
//! to enable it (see the [Crate Features](#crate-features) section).
//!
//! Please also note a few things about this backend:
//! Please also note a few things about **rustls**:
//!
//! * it will fail if you'll try to connect to the server by its IP address, hostname is required;
//! * it, most likely, won't work on windows, at least with default server certs, generated by the
Expand All @@ -801,8 +830,6 @@
#[cfg(feature = "nightly")]
extern crate test;

use std::sync::Arc;

use mysql_common as myc;
pub extern crate serde;
pub extern crate serde_json;
Expand Down Expand Up @@ -894,9 +921,6 @@ pub mod prelude {
#[doc(inline)]
pub use crate::myc::params;

static BUFFER_POOL: once_cell::sync::Lazy<Arc<crate::buffer_pool::BufferPool>> =
once_cell::sync::Lazy::new(|| Default::default());

#[doc(hidden)]
#[macro_export]
macro_rules! def_database_url {
Expand Down

0 comments on commit 1edd17e

Please sign in to comment.