forked/hyper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ffi): generate FFI documentation (#2447)

Browse Source
This commit is contained in:
Sean McArthur
2021-02-26 19:00:37 -08:00
committed by GitHub
parent 4c946af49c
commit f162ca2f2f
10 changed files with 73 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/CI.yml vendored
View File

@@ -179,4 +179,4 @@ jobs:
uses: actions-rs/cargo@v1 uses: actions-rs/cargo@v1
with: with:
command: rustdoc command: rustdoc
args: --features full -- --cfg docsrs -D broken-intra-doc-links args: --features full,ffi -- --cfg docsrs --cfg hyper_unstable_ffi -D broken-intra-doc-links

4
Cargo.toml
View File

@@ -118,8 +118,8 @@ nightly = []
__internal_happy_eyeballs_tests = [] __internal_happy_eyeballs_tests = []
[package.metadata.docs.rs] [package.metadata.docs.rs]
features = ["full"] features = ["ffi", "full"]
rustdoc-args = ["--cfg", "docsrs"] rustdoc-args = ["--cfg", "docsrs", "--cfg", "hyper_unstable_ffi"]
[package.metadata.playground] [package.metadata.playground]
features = ["full"] features = ["full"]

2
src/ffi/body.rs
View File

@@ -10,8 +10,10 @@ use super::task::{hyper_context, hyper_task, hyper_task_return_type, AsTaskType}
use super::{UserDataPointer, HYPER_ITER_CONTINUE}; use super::{UserDataPointer, HYPER_ITER_CONTINUE};
use crate::body::{Body, Bytes, HttpBody as _}; use crate::body::{Body, Bytes, HttpBody as _};
/// A streaming HTTP body.
pub struct hyper_body(pub(super) Body); pub struct hyper_body(pub(super) Body);
/// A buffer of bytes that is sent or received on a `hyper_body`.
pub struct hyper_buf(pub(super) Bytes); pub struct hyper_buf(pub(super) Bytes);
pub(crate) struct UserBody { pub(crate) struct UserBody {

6
src/ffi/client.rs
View File

@@ -10,12 +10,18 @@ use super::http_types::{hyper_request, hyper_response};
use super::io::hyper_io; use super::io::hyper_io;
use super::task::{hyper_executor, hyper_task, hyper_task_return_type, AsTaskType, WeakExec}; use super::task::{hyper_executor, hyper_task, hyper_task_return_type, AsTaskType, WeakExec};
/// An options builder to configure an HTTP client connection.
pub struct hyper_clientconn_options { pub struct hyper_clientconn_options {
builder: conn::Builder, builder: conn::Builder,
/// Use a `Weak` to prevent cycles. /// Use a `Weak` to prevent cycles.
exec: WeakExec, exec: WeakExec,
} }
/// An HTTP client connection handle.
///
/// These are used to send a request on a single connection. It's possible to
/// send multiple requests on a single connection, such as when HTTP/1
/// keep-alive or HTTP/2 is used.
pub struct hyper_clientconn { pub struct hyper_clientconn {
tx: conn::SendRequest<crate::Body>, tx: conn::SendRequest<crate::Body>,
} }

2
src/ffi/error.rs
View File

@@ -1,7 +1,9 @@
use libc::size_t; use libc::size_t;
/// A more detailed error object returned by some hyper functions.
pub struct hyper_error(crate::Error); pub struct hyper_error(crate::Error);
/// A return code for many of hyper's methods.
#[repr(C)] #[repr(C)]
pub enum hyper_code { pub enum hyper_code {
/// All is well. /// All is well.

5
src/ffi/http_types.rs
View File

@@ -9,10 +9,15 @@ use super::HYPER_ITER_CONTINUE;
use crate::header::{HeaderName, HeaderValue}; use crate::header::{HeaderName, HeaderValue};
use crate::{Body, HeaderMap, Method, Request, Response, Uri}; use crate::{Body, HeaderMap, Method, Request, Response, Uri};
/// An HTTP request.
pub struct hyper_request(pub(super) Request<Body>); pub struct hyper_request(pub(super) Request<Body>);
/// An HTTP response.
pub struct hyper_response(pub(super) Response<Body>); pub struct hyper_response(pub(super) Response<Body>);
/// An HTTP header map.
///
/// These can be part of a request or response.
#[derive(Default)] #[derive(Default)]
pub struct hyper_headers { pub struct hyper_headers {
pub(super) headers: HeaderMap, pub(super) headers: HeaderMap,

5
src/ffi/io.rs
View File

@@ -7,7 +7,11 @@ use tokio::io::{AsyncRead, AsyncWrite};
use super::task::hyper_context; use super::task::hyper_context;
/// Sentinal value to return from a read or write callback that the operation
/// is pending.
pub const HYPER_IO_PENDING: size_t = 0xFFFFFFFF; pub const HYPER_IO_PENDING: size_t = 0xFFFFFFFF;
/// Sentinal value to return from a read or write callback that the operation
/// has errored.
pub const HYPER_IO_ERROR: size_t = 0xFFFFFFFE; pub const HYPER_IO_ERROR: size_t = 0xFFFFFFFE;
type hyper_io_read_callback = type hyper_io_read_callback =
@@ -15,6 +19,7 @@ type hyper_io_read_callback =
type hyper_io_write_callback = type hyper_io_write_callback =
extern "C" fn(*mut c_void, *mut hyper_context<'_>, *const u8, size_t) -> size_t; extern "C" fn(*mut c_void, *mut hyper_context<'_>, *const u8, size_t) -> size_t;
/// An IO object used to represent a socket or similar concept.
pub struct hyper_io { pub struct hyper_io {
read: hyper_io_read_callback, read: hyper_io_read_callback,
write: hyper_io_write_callback, write: hyper_io_write_callback,

38
src/ffi/mod.rs
View File

@@ -1,8 +1,33 @@
// We have a lot of c-types in here, stop warning about their names! // We have a lot of c-types in here, stop warning about their names!
#![allow(non_camel_case_types)] #![allow(non_camel_case_types)]
// fmt::Debug isn't helpful on FFI types
#![allow(missing_debug_implementations)]
// unreachable_pub warns `#[no_mangle] pub extern fn` in private mod. // unreachable_pub warns `#[no_mangle] pub extern fn` in private mod.
#![allow(unreachable_pub)] #![allow(unreachable_pub)]
//! # hyper C API
//!
//! This part of the documentation describes the C API for hyper. That is, how
//! to *use* the hyper library in C code. This is **not** a regular Rust
//! module, and thus it is not accessible in Rust.
//!
//! ## Unstable
//!
//! The C API of hyper is currently **unstable**, which means it's not part of
//! the semver contract as the rest of the Rust API is. Because of that, it's
//! only accessible if `--cfg hyper_unstable_ffi` is passed to `rustc` when
//! compiling. The easiest way to do that is setting the `RUSTFLAGS`
//! environment variable.
//!
//! ## Building
//!
//! The C API is part of the Rust library, but isn't compiled by default. Using
//! `cargo`, it can be compiled with the following command:
//!
//! ```notrust
//! RUSTFLAGS="--cfg hyper_unstable_ffi" cargo build --features client,http1,http2,ffi
//! ```
// We may eventually allow the FFI to be enabled without `client` or `http1`, // We may eventually allow the FFI to be enabled without `client` or `http1`,
// that is why we don't auto enable them as `ffi = ["client", "http1"]` in // that is why we don't auto enable them as `ffi = ["client", "http1"]` in
// the `Cargo.toml`. // the `Cargo.toml`.
@@ -29,16 +54,29 @@ mod http_types;
mod io; mod io;
mod task; mod task;
pub use self::body::*;
pub use self::client::*;
pub use self::error::*;
pub use self::http_types::*;
pub use self::io::*;
pub use self::task::*;
pub(crate) use self::body::UserBody; pub(crate) use self::body::UserBody;
pub(crate) use self::http_types::{HeaderCaseMap, ReasonPhrase}; pub(crate) use self::http_types::{HeaderCaseMap, ReasonPhrase};
/// Return in iter functions to continue iterating.
pub const HYPER_ITER_CONTINUE: libc::c_int = 0; pub const HYPER_ITER_CONTINUE: libc::c_int = 0;
/// Return in iter functions to stop iterating.
#[allow(unused)] #[allow(unused)]
pub const HYPER_ITER_BREAK: libc::c_int = 1; pub const HYPER_ITER_BREAK: libc::c_int = 1;
/// An HTTP Version that is unspecified.
pub const HYPER_HTTP_VERSION_NONE: libc::c_int = 0; pub const HYPER_HTTP_VERSION_NONE: libc::c_int = 0;
/// The HTTP/1.0 version.
pub const HYPER_HTTP_VERSION_1_0: libc::c_int = 10; pub const HYPER_HTTP_VERSION_1_0: libc::c_int = 10;
/// The HTTP/1.1 version.
pub const HYPER_HTTP_VERSION_1_1: libc::c_int = 11; pub const HYPER_HTTP_VERSION_1_1: libc::c_int = 11;
/// The HTTP/2 version.
pub const HYPER_HTTP_VERSION_2: libc::c_int = 20; pub const HYPER_HTTP_VERSION_2: libc::c_int = 20;
struct UserDataPointer(*mut std::ffi::c_void); struct UserDataPointer(*mut std::ffi::c_void);

11
src/ffi/task.rs
View File

@@ -17,10 +17,17 @@ use super::UserDataPointer;
type BoxFuture<T> = Pin<Box<dyn Future<Output = T> + Send>>; type BoxFuture<T> = Pin<Box<dyn Future<Output = T> + Send>>;
type BoxAny = Box<dyn AsTaskType + Send + Sync>; type BoxAny = Box<dyn AsTaskType + Send + Sync>;
/// Return in a poll function to indicate it was ready.
pub const HYPER_POLL_READY: c_int = 0; pub const HYPER_POLL_READY: c_int = 0;
/// Return in a poll function to indicate it is still pending.
///
/// The passed in `hyper_waker` should be registered to wake up the task at
/// some later point.
pub const HYPER_POLL_PENDING: c_int = 1; pub const HYPER_POLL_PENDING: c_int = 1;
/// Return in a poll function indicate an error.
pub const HYPER_POLL_ERROR: c_int = 3; pub const HYPER_POLL_ERROR: c_int = 3;
/// A task executor for `hyper_task`s.
pub struct hyper_executor { pub struct hyper_executor {
/// The executor of all task futures. /// The executor of all task futures.
/// ///
@@ -47,6 +54,7 @@ pub(crate) struct WeakExec(Weak<hyper_executor>);
struct ExecWaker(AtomicBool); struct ExecWaker(AtomicBool);
/// An async task.
pub struct hyper_task { pub struct hyper_task {
future: BoxFuture<BoxAny>, future: BoxFuture<BoxAny>,
output: Option<BoxAny>, output: Option<BoxAny>,
@@ -57,12 +65,15 @@ struct TaskFuture {
task: Option<Box<hyper_task>>, task: Option<Box<hyper_task>>,
} }
/// An async context for a task that contains the related waker.
pub struct hyper_context<'a>(Context<'a>); pub struct hyper_context<'a>(Context<'a>);
/// A waker that is saved and used to waken a pending task.
pub struct hyper_waker { pub struct hyper_waker {
waker: std::task::Waker, waker: std::task::Waker,
} }
/// A descriptor for what type a `hyper_task` value is.
#[repr(C)] #[repr(C)]
pub enum hyper_task_return_type { pub enum hyper_task_return_type {
/// The value of this task is null (does not imply an error). /// The value of this task is null (does not imply an error).

2
src/lib.rs
View File

@@ -89,7 +89,7 @@ pub mod service;
pub mod upgrade; pub mod upgrade;
#[cfg(feature = "ffi")] #[cfg(feature = "ffi")]
mod ffi; pub mod ffi;
cfg_proto! { cfg_proto! {
mod headers; mod headers;