taskchampion_lib/
lib.rs

1//! # DEPRECATED
2//!
3//! This crate is deprecated. Consumers of TaskChampion are encouraged to build their own FFI
4//! interface.
5//! [Taskwarrior](https://github.com/GothenburgBitFactory/taskwarrior/tree/develop/src/tc/lib)
6//! provides one example (based on this crate).
7
8#![warn(unsafe_op_in_unsafe_fn)]
9#![allow(unused_unsafe)]
10// Not working yet in stable - https://github.com/rust-lang/rust-clippy/issues/8020
11// #![warn(clippy::undocumented_unsafe_blocks)]
12
13// docstrings for extern "C" functions are reflected into C, and do not benefit
14// from safety docs.
15#![allow(clippy::missing_safety_doc)]
16// deny some things that are typically warnings
17#![deny(clippy::derivable_impls)]
18#![deny(clippy::wrong_self_convention)]
19#![deny(clippy::extra_unused_lifetimes)]
20#![deny(clippy::unnecessary_to_owned)]
21
22// ffizz_header orders:
23//
24// 000-099: header matter
25// 100-199: TCResult
26// 200-299: TCString / List
27// 300-399: TCUuid / List
28// 400-499: TCAnnotation / List
29// 500-599: TCUda / List
30// 600-699: TCKV / List
31// 700-799: TCStatus
32// 800-899: TCServer
33// 900-999: TCReplica
34// 1000-1099: TCTask / List
35// 1100-1199: TCWorkingSet
36// 10000-10099: footer
37
38ffizz_header::snippet! {
39#[ffizz(name="intro", order=0)]
40/// TaskChampion
41///
42/// This file defines the C interface to libtaskchampion.  This is a thin wrapper around the Rust
43/// `taskchampion` crate.  Refer to the documentation for that crate at
44/// https://docs.rs/taskchampion/latest/taskchampion/ for API details.  The comments in this file
45/// focus mostly on the low-level details of passing values to and from TaskChampion.
46///
47/// # Overview
48///
49/// This library defines four major types used to interact with the API, that map directly to Rust
50/// types.
51///
52///  * TCReplica - see https://docs.rs/taskchampion/latest/taskchampion/struct.Replica.html
53///  * TCTask - see https://docs.rs/taskchampion/latest/taskchampion/struct.Task.html
54///  * TCServer - see https://docs.rs/taskchampion/latest/taskchampion/trait.Server.html
55///  * TCWorkingSet - see https://docs.rs/taskchampion/latest/taskchampion/struct.WorkingSet.html
56///
57/// It also defines a few utility types:
58///
59///  * TCString - a wrapper around both C (NUL-terminated) and Rust (always utf-8) strings.
60///  * TC…List - a list of objects represented as a C array
61///  * see below for the remainder
62///
63/// # Safety
64///
65/// Each type contains specific instructions to ensure memory safety.  The general rules are as
66/// follows.
67///
68/// No types in this library are threadsafe.  All values should be used in only one thread for their
69/// entire lifetime.  It is safe to use unrelated values in different threads (for example,
70/// different threads may use different TCReplica values concurrently).
71///
72/// ## Pass by Pointer
73///
74/// Several types such as TCReplica and TCString are "opaque" types and always handled as pointers
75/// in C. The bytes these pointers address are private to the Rust implementation and must not be
76/// accessed from C.
77///
78/// Pass-by-pointer values have exactly one owner, and that owner is responsible for freeing the
79/// value (using a `tc_…_free` function), or transferring ownership elsewhere.  Except where
80/// documented otherwise, when a value is passed to C, ownership passes to C as well.  When a value
81/// is passed to Rust, ownership stays with the C code.  The exception is TCString, ownership of
82/// which passes to Rust when it is used as a function argument.
83///
84/// The limited circumstances where one value must not outlive another, due to pointer references
85/// between them, are documented below.
86///
87/// ## Pass by Value
88///
89/// Types such as TCUuid and TC…List are passed by value, and contain fields that are accessible
90/// from C.  C code is free to access the content of these types in a _read_only_ fashion.
91///
92/// Pass-by-value values that contain pointers also have exactly one owner, responsible for freeing
93/// the value or transferring ownership.  The tc_…_free functions for these types will replace the
94/// pointers with NULL to guard against use-after-free errors.  The interior pointers in such values
95/// should never be freed directly (for example, `tc_string_free(tcuda.value)` is an error).
96///
97/// TCUuid is a special case, because it does not contain pointers.  It can be freely copied and
98/// need not be freed.
99///
100/// ## Lists
101///
102/// Lists are a special kind of pass-by-value type.  Each contains `len` and `items`, where `items`
103/// is an array of length `len`.  Lists, and the values in the `items` array, must be treated as
104/// read-only.  On return from an API function, a list's ownership is with the C caller, which must
105/// eventually free the list.  List data must be freed with the `tc_…_list_free` function.  It is an
106/// error to free any value in the `items` array of a list.
107}
108
109ffizz_header::snippet! {
110#[ffizz(name="topmatter", order=1)]
111/// ```c
112/// #ifndef TASKCHAMPION_H
113/// #define TASKCHAMPION_H
114///
115/// #include <stdbool.h>
116/// #include <stdint.h>
117/// #include <time.h>
118///
119/// #ifdef __cplusplus
120/// #define EXTERN_C extern "C"
121/// #else
122/// #define EXTERN_C
123/// #endif // __cplusplus
124/// ```
125}
126
127ffizz_header::snippet! {
128#[ffizz(name="bottomatter", order=10000)]
129/// ```c
130/// #endif /* TASKCHAMPION_H */
131/// ```
132}
133
134mod traits;
135mod util;
136
137pub mod annotation;
138pub use annotation::*;
139pub mod atomic;
140pub mod kv;
141pub use kv::*;
142pub mod replica;
143pub use replica::*;
144pub mod result;
145pub use result::*;
146pub mod server;
147pub use server::*;
148pub mod status;
149pub use status::*;
150pub mod string;
151pub use string::*;
152pub mod task;
153pub use task::*;
154pub mod uda;
155pub use uda::*;
156pub mod uuid;
157pub use uuid::*;
158pub mod workingset;
159pub use workingset::*;
160
161pub(crate) mod types {
162    pub(crate) use crate::annotation::{TCAnnotation, TCAnnotationList};
163    pub(crate) use crate::kv::TCKVList;
164    pub(crate) use crate::replica::TCReplica;
165    pub(crate) use crate::result::TCResult;
166    pub(crate) use crate::server::TCServer;
167    pub(crate) use crate::status::TCStatus;
168    pub(crate) use crate::string::{RustString, TCString, TCStringList};
169    pub(crate) use crate::task::{TCTask, TCTaskList};
170    pub(crate) use crate::uda::{TCUda, TCUdaList, Uda};
171    pub(crate) use crate::uuid::{TCUuid, TCUuidList};
172    pub(crate) use crate::workingset::TCWorkingSet;
173}
174
175/// Generate the taskchapion.h header
176pub fn generate_header() -> String {
177    ffizz_header::generate()
178}
taskchampion_lib/lib.rs

taskchampion_lib/
lib.rs
