glib/
lib.rs

1// Copyright 2013-2016, The Gtk-rs Project Developers.
2// See the COPYRIGHT file at the top-level directory of this distribution.
3// Licensed under the MIT license, see the LICENSE file or <http://opensource.org/licenses/MIT>
4
5//! # **glib**, **gobject** and **gio** bindings for Rust
6//!
7//! This library contains
8//!
9//! - bindings to some essential GLib, GObject, GIO types and APIs,
10//!
11//! - common building blocks used in both handmade and machine generated
12//! bindings to GTK+ and other GLib-based libraries.
13//!
14//! It is the foundation for higher level libraries with uniform Rusty (safe and
15//! strongly typed) APIs. It avoids exposing GLib-specific data types where
16//! possible and is not meant to provide comprehensive GLib bindings, which
17//! would often amount to duplicating the Rust Standard Library or other utility
18//! crates.
19//!
20//! The library is a work in progress: expect missing functionality and breaking
21//! changes.
22//!
23//! # Dynamic typing
24//!
25//! Most types in the GLib family have type identifiers
26//! ([`Type`](types/enum.Type.html)). Their corresponding Rust types implement
27//! the [`StaticType`](types/trait.StaticType.html) trait.
28//!
29//! Dynamically typed [`Value`](value/index.html) can carry values of any `T:
30//! StaticType`.
31//!
32//! [`Variant`](variant/index.html) can carry values of `T: StaticVariantType`.
33//!
34//! # Errors
35//!
36//! Errors are represented by [`Error`](error/struct.Error.html), which can
37//! carry values from various [error
38//! domains](error/trait.ErrorDomain.html#implementors) (such as
39//! [`FileError`](enum.FileError.html)).
40//!
41//! # Objects
42//!
43//! Each class and interface has a corresponding smart pointer struct
44//! representing an instance of that type (e.g. `Object` for `GObject`,
45//! `gtk::Widget` for `GtkWidget`). They are reference counted and feature
46//! interior mutability similarly to Rust's `Rc<RefCell<T>>` idiom.
47//! Consequently, cloning objects is cheap and their methods never require
48//! mutable borrows. Two smart pointers are equal iff they point to the same
49//! object.
50//!
51//! The root of the object hierarchy is [`Object`](object/struct.Object.html).
52//! Inheritance and subtyping is denoted with the [`IsA`](object/trait.IsA.html)
53//! marker trait. The [`Cast`](object/trait.Cast.html) trait enables upcasting
54//! and downcasting.
55//!
56//! Interfaces and non-leaf classes also have corresponding traits (e.g.
57//! `ObjectExt` and `gtk::WidgetExt`), which are blanketly implemented for all
58//! their subtypes.
59//!
60//! For creating new subclasses of `Object` or other object types this crate has to be compiled
61//! with the `subclassing` feature to enable the [`subclass`](subclass/index.html) module. Check
62//! the module's documentation for further details and a code example.
63//!
64//! # Under the hood
65//!
66//! GLib-based libraries largely operate on pointers to various boxed or
67//! reference counted structures so the bindings have to implement corresponding
68//! smart pointers (wrappers), which encapsulate resource management and safety
69//! checks. Such wrappers are defined via the
70//! [`glib_wrapper!`](macro.glib_wrapper!.html) macro, which uses abstractions
71//! defined in the [`wrapper`](wrapper/index.html), [`boxed`](boxed/index.html),
72//! [`shared`](shared/index.html) and [`object`](object/index.html) modules.
73//!
74//! The [`translate`](translate/index.html) module defines and partly implements
75//! conversions between high level Rust types (including the aforementioned
76//! wrappers) and their FFI counterparts.
77
78#![allow(clippy::doc_markdown)]
79#![allow(clippy::unreadable_literal)]
80
81#[macro_use]
82extern crate bitflags;
83#[macro_use]
84extern crate lazy_static;
85extern crate libc;
86
87#[doc(hidden)]
88pub extern crate glib_sys;
89#[doc(hidden)]
90pub extern crate gobject_sys;
91
92#[cfg(feature = "futures")]
93pub extern crate futures;
94
95pub use byte_array::ByteArray;
96pub use bytes::Bytes;
97pub use closure::Closure;
98pub use error::{BoolError, Error};
99pub use file_error::FileError;
100pub use object::{
101    Cast, InitiallyUnowned, InitiallyUnownedClass, IsA, IsClassFor, Object, ObjectClass, ObjectExt,
102    ObjectType, SendWeakRef, WeakRef,
103};
104pub use signal::{
105    signal_handler_block, signal_handler_disconnect, signal_handler_unblock,
106    signal_stop_emission_by_name, SignalHandlerId,
107};
108use std::ffi::CStr;
109pub use string::String;
110
111pub use enums::{EnumClass, EnumValue, FlagsBuilder, FlagsClass, FlagsValue, UserDirectory};
112pub use time_val::{get_current_time, TimeVal};
113pub use types::{StaticType, Type};
114pub use value::{SendValue, ToSendValue, ToValue, TypedValue, Value};
115pub use variant::{StaticVariantType, ToVariant, Variant};
116pub use variant_type::{VariantTy, VariantType};
117
118#[macro_use]
119pub mod wrapper;
120#[macro_use]
121pub mod boxed;
122#[macro_use]
123pub mod shared;
124#[macro_use]
125pub mod error;
126#[macro_use]
127pub mod object;
128
129pub use auto::functions::*;
130pub use auto::*;
131#[allow(clippy::let_and_return)]
132#[allow(clippy::let_unit_value)]
133#[allow(clippy::too_many_arguments)]
134#[allow(non_upper_case_globals)]
135mod auto;
136
137pub use gobject::*;
138mod gobject;
139
140mod byte_array;
141mod bytes;
142pub mod char;
143mod string;
144pub use char::*;
145mod checksum;
146pub mod closure;
147mod enums;
148mod file_error;
149mod key_file;
150pub mod prelude;
151pub mod signal;
152pub mod source;
153pub use source::*;
154mod time_val;
155#[macro_use]
156pub mod translate;
157mod gstring;
158pub use gstring::GString;
159pub mod types;
160mod utils;
161pub use utils::*;
162mod main_context;
163mod main_context_channel;
164pub mod value;
165pub mod variant;
166mod variant_type;
167pub use main_context_channel::{Receiver, Sender, SyncSender};
168mod date;
169pub use date::Date;
170mod value_array;
171pub use value_array::ValueArray;
172mod param_spec;
173pub use param_spec::ParamSpec;
174mod quark;
175pub use quark::Quark;
176
177pub mod send_unique;
178pub use send_unique::{SendUnique, SendUniqueCell};
179
180#[cfg(feature = "futures")]
181mod main_context_futures;
182#[cfg(feature = "futures")]
183mod source_futures;
184#[cfg(feature = "futures")]
185pub use source_futures::*;
186
187// Actual thread IDs can be reused by the OS once the old thread finished.
188// This works around it by using our own counter for threads.
189//
190// Taken from the fragile crate
191use std::sync::atomic::{AtomicUsize, Ordering};
192fn next_thread_id() -> usize {
193    static mut COUNTER: AtomicUsize = AtomicUsize::new(0);
194    unsafe { COUNTER.fetch_add(1, Ordering::SeqCst) }
195}
196
197pub(crate) fn get_thread_id() -> usize {
198    thread_local!(static THREAD_ID: usize = next_thread_id());
199    THREAD_ID.with(|&x| x)
200}
201
202#[macro_use]
203#[cfg(any(feature = "dox", feature = "subclassing"))]
204pub mod subclass;