From 77eefe01760d79ded2051a3b2cd390e41751e2dd Mon Sep 17 00:00:00 2001 From: Ben S Date: Tue, 26 Jan 2016 19:17:24 +0000 Subject: [PATCH] Rename OSUsers to UsersCache It's more descriptive to call it a cache when there are functions that do all the *actual* OS users stuff separately now. Similarly, we may as well call its constructor 'new' instead of 'empty_cache', because it's obvious that it's a cache now. --- examples/example.rs | 4 ++-- examples/threading.rs | 8 ++++---- src/{os.rs => cache.rs} | 22 +++++++++++----------- src/lib.rs | 20 ++++++++++---------- src/mock.rs | 6 +++--- 5 files changed, 30 insertions(+), 30 deletions(-) rename src/{os.rs => cache.rs} (96%) diff --git a/examples/example.rs b/examples/example.rs index 069d0ef..c2f34a5 100644 --- a/examples/example.rs +++ b/examples/example.rs @@ -1,8 +1,8 @@ extern crate users; -use users::{Users, Groups, OSUsers}; +use users::{Users, Groups, UsersCache}; fn main() { - let cache = OSUsers::empty_cache(); + let cache = UsersCache::new(); let current_uid = cache.get_current_uid(); println!("Your UID is {}", current_uid); diff --git a/examples/threading.rs b/examples/threading.rs index 24ac1a3..27ffa54 100644 --- a/examples/threading.rs +++ b/examples/threading.rs @@ -1,4 +1,4 @@ -//! This example demonstrates how to use an `OSUsers` cache in a +//! This example demonstrates how to use a `UsersCache` cache in a //! multi-threaded situation. The cache uses `RefCell`s internally, so it //! is distinctly not thread-safe. Instead, you’ll need to place it within //! some kind of lock in order to have threads access it one-at-a-time. @@ -16,7 +16,7 @@ // spew compile errors at you. extern crate users; -use users::{Users, OSUsers, uid_t}; +use users::{Users, UsersCache, uid_t}; use std::sync::{Arc, Mutex}; use std::time::Duration; @@ -30,8 +30,8 @@ fn main() { // For thread-safely, our users cache needs to be within a Mutex, so // only one thread can access it once. This Mutex needs to be within an // Arc, so multiple threads can access the Mutex. - let cache = Arc::new(Mutex::new(OSUsers::empty_cache())); - // let cache = OSUsers::empty_cache(); + let cache = Arc::new(Mutex::new(UsersCache::new())); + // let cache = UsersCache::empty_cache(); // Loop over the range and query all the users in the range. Although we // could use the `&User` values returned, we just ignore them. diff --git a/src/os.rs b/src/cache.rs similarity index 96% rename from src/os.rs rename to src/cache.rs index 7870fca..bd96834 100644 --- a/src/os.rs +++ b/src/cache.rs @@ -2,7 +2,7 @@ //! //! ## Caching, multiple threads, and mutability //! -//! The `OSUsers` type is caught between a rock and a hard place when it comes +//! The `UsersCache` type is caught between a rock and a hard place when it comes //! to providing references to users and groups. //! //! Instead of returning a fresh `User` struct each time, for example, it will @@ -25,7 +25,7 @@ //! to be read at a time! //! //! ``norun -//! let mut cache = OSUsers::empty_cache(); +//! let mut cache = UsersCache::empty_cache(); //! let uid = cache.get_current_uid(); // OK... //! let user = cache.get_user_by_uid(uid).unwrap() // OK... //! let group = cache.get_group_by_gid(user.primary_group); // No! @@ -73,7 +73,7 @@ use traits::{Users, Groups}; /// A producer of user and group instances that caches every result. -pub struct OSUsers { +pub struct UsersCache { users: BiMap, groups: BiMap, @@ -97,9 +97,9 @@ struct BiMap { // Default impl on User or Group, even though those types aren't // needed to produce a default instance of any HashMaps... -impl Default for OSUsers { - fn default() -> OSUsers { - OSUsers { +impl Default for UsersCache { + fn default() -> UsersCache { + UsersCache { users: BiMap { forward: RefCell::new(HashMap::new()), backward: RefCell::new(HashMap::new()), @@ -118,15 +118,15 @@ impl Default for OSUsers { } } -impl OSUsers { +impl UsersCache { /// Create a new empty cache. - pub fn empty_cache() -> OSUsers { - OSUsers::default() + pub fn new() -> UsersCache { + UsersCache::default() } } -impl Users for OSUsers { +impl Users for UsersCache { fn get_user_by_uid(&self, uid: uid_t) -> Option> { let mut users_forward = self.users.forward.borrow_mut(); @@ -219,7 +219,7 @@ impl Users for OSUsers { } } -impl Groups for OSUsers { +impl Groups for UsersCache { fn get_group_by_gid(&self, gid: gid_t) -> Option> { let mut groups_forward = self.groups.forward.borrow_mut(); diff --git a/src/lib.rs b/src/lib.rs index 9950bce..a3f185e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -60,12 +60,12 @@ //! which offers the same functionality while holding on to every result, //! caching the information so it can be re-used. //! -//! To introduce a cache, create a new `OSUsers` object and call the same +//! To introduce a cache, create a new `UsersCache` and call the same //! methods on it. For example: //! //! ```rust -//! use users::{Users, Groups, OSUsers}; -//! let mut cache = OSUsers::empty_cache(); +//! use users::{Users, Groups, UsersCache}; +//! let mut cache = UsersCache::new(); //! let uid = cache.get_current_uid(); //! let user = cache.get_user_by_uid(uid).unwrap(); //! println!("Hello again, {}!", user.name); @@ -74,13 +74,13 @@ //! This cache is **only additive**: it’s not possible to drop it, or erase //! selected entries, as when the database may have been modified, it’s best to //! start entirely afresh. So to accomplish this, just start using a new -//! `OSUsers` object. +//! `UsersCache`. //! //! //! ## Groups //! //! Finally, it’s possible to get groups in a similar manner. -//! A `Group` object has the following public fields: +//! A `Group` has the following public fields: //! //! - **gid:** The group’s ID //! - **name:** The group’s name @@ -89,8 +89,8 @@ //! And again, a complete example: //! //! ```rust -//! use users::{Users, Groups, OSUsers}; -//! let mut cache = OSUsers::empty_cache(); +//! use users::{Users, Groups, UsersCache}; +//! let mut cache = UsersCache::new(); //! let group = cache.get_group_by_name("admin").expect("No such group 'admin'!"); //! println!("The '{}' group has the ID {}", group.name, group.gid); //! for member in &group.members { @@ -114,12 +114,12 @@ pub use libc::{uid_t, gid_t}; mod base; pub use base::*; +pub mod cache; +pub use cache::UsersCache; + pub mod mock; -pub mod os; -pub use os::OSUsers; pub mod switch; -use switch::*; mod traits; pub use traits::{Users, Groups}; diff --git a/src/mock.rs b/src/mock.rs index 23f9fd2..65c7c0d 100644 --- a/src/mock.rs +++ b/src/mock.rs @@ -32,12 +32,12 @@ //! //! To set your program up to use either type of Users object, make your //! functions and structs accept a generic parameter that implements the `Users` -//! trait. Then, you can pass in an object of either OS or Mock type. +//! trait. Then, you can pass in a value of either Cache or Mock type. //! //! Here's a complete example: //! //! ```rust -//! use users::{Users, OSUsers, User}; +//! use users::{Users, UsersCache, User}; //! use users::mock::MockUsers; //! use std::sync::Arc; //! @@ -49,7 +49,7 @@ //! users.add_user(User { uid: 1001, name: Arc::new("fred".to_string()), primary_group: 101 , home_dir: "/home/fred".to_string(), shell: "/bin/bash".to_string()}); //! print_current_username(&mut users); //! -//! let mut actual_users = OSUsers::empty_cache(); +//! let mut actual_users = UsersCache::new(); //! print_current_username(&mut actual_users); //! ```