From 6f343b3105eceef728d94ec120bd3320bce27225 Mon Sep 17 00:00:00 2001
From: Dirk Van Haerenborgh <vhdirk@gmail.com>
Date: Sat, 14 Apr 2018 12:03:16 +0200
Subject: add readme and test

---
 README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 README.md

(limited to 'README.md')

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f4de423
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+notmuch-rs
+==========
+
+This is not much more than a wrapper for the [notmuch](https://notmuchmail.org/) C api.
+
+## Building
+**notmuch-rs** expects libnotmuch development files to be installed on your system.
+
+
+## Using
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+notmuch = "*"
+```
+
+and this to your crate root:
+
+```rust
+extern crate notmuch;
+```
+
+## Example
+
+```rust
+extern crate notmuch;
+
+fn main() {
+
+    let mut mail_path = std::env::home_dir().unwrap();
+    mail_path.push(".mail");
+
+    let db = notmuch::Database::open(&mail_path.to_str().unwrap().to_string(), notmuch::DatabaseMode::ReadOnly).unwrap();
+    let query = db.create_query(&"".to_string()).unwrap();
+    let mut threads = query.search_threads().unwrap();
+
+    loop {
+        match threads.next() {
+            Some(thread) => {
+                println!("thread {:?} {:?}", thread.subject(), thread.authors());
+            },
+            None => { break }
+        }
+    }
+}
+
+```
+
+## Concurrency
+
+Notmuch makes no claims regarding thread safety. It does not seem to use any
+thread locals, but I did not spot any locks. So, as far as I am concerned, it is
+not thread safe.  
+So why do all structs implement ```Send``` and ```Sync```? Well, it _is_ safe to
+access pointers from different threads (as long as you know what you are doing :) ).
+But, more importantly, all structs are strictly linked together with their
+lifetime. The root of the tree is ```notmuch::Database```, which has a lifetime
+that must outlive any related objects, for instance ```notmuch::Query```. The
+```notmuch::Threads``` iterator that you can get from a ```notmuch::Query``` is
+always outlived by the parent query.  
+This means that you can only use these structs accross thread bounds if you
+figure out how to satisfy the lifetime requirements. Up until now, I haven't
+been able to do that (though my knowledge of Rust is still rather basic).  
+So, concurrency seems currently limited to scoped threads.
+
+## Acknowledgements
+
+notmuch-rs started out from the following projects:
+ - https://github.com/Stebalien/notmuch-sys/blob/master/src/lib.rs
+ - https://github.com/cmhamill/rust-notmuch
+
+Any contributions are welcome!
-- 
cgit v1.2.1