# Voluntary Servitude
* [Docs](https://docs.rs/crate/voluntary-servitude/1.0.0)
- Currently implements a thread-safe appendable list with a lock-free iterator
- FFI implementation available, C examples are in **./examples** folder
cd examples && make test
- Last release is in **./dist**
- Uses system allocator by default, jemmaloc can be enabled with the 'jemmaloc' feature
- Logging is available behind the 'logs' feature and RUST_LOG env var
## Basic usage
### Single thread
```
// Creates VSRead with 3 elements
// vsread![] makes an empty VSRead
// vsread![1; 3] makes a VSRead with 3 elements equal to 1
let list = vsread![0, 1, 2];
assert_eq!(list.len(), 3);
// The 'iter' method makes a one-time lock-free iterator (VSReadIter) based on VSRead
assert_eq!(list.iter().len(), 3);
// You can get the current iteration index
assert_eq!(list.iter().index(), 0);
// Appends 9997 elements to it
assert_eq!((3..10000).map(|i| list.append(i)).count(), 9997);
// Iterates through all elements to ensure it's what we inserted
let count = list.iter().enumerate().map(|(i, el)| assert_eq!(&i, el)).count();
assert_eq!(count, 10000);
// List can also be cleared
list.clear();
assert_eq!(list.len(), 0);
```
### Multi producer, multi consumer
```
use std::{thread::spawn, sync::Arc};
const CONSUMERS: usize = 8;
const PRODUCERS: usize = 4;
fn main() {
let list = Arc::new(vsread![]); // or Arc::new(VSRead::default());
let mut handlers = vec![];
// Creates producer threads to insert 10k elements each
for _ in 0..PRODUCERS {
let l = Arc::clone(&list);
handlers.push(spawn(move || { let _ = (0..10000).map(|i| l.append(i)).count(); }));
}
// Creates consumer threads to print number of elements until all elements are inserted
for _ in 0..CONSUMERS {
let consumer = Arc::clone(&list);
handlers.push(spawn(move || {
loop {
let count = consumer.iter().count();
println!("{} elements", count);
if count == PRODUCERS * 10000 { break; }
}
}));
}
// Join threads
for handler in handlers.into_iter() {
handler.join().expect("Failed to join thread");
}
}
```
### Single thread C example (FFI)
```
#include<assert.h>
#include "include/voluntary_servitude.h"
int main(int argc, char **argv) {
// Rust allocates memory through malloc
vsread_t * const vsread = vsread_new();
// Current vsread_t length
// Be careful with data-races since the value, when used, may not be true anymore
assert(vsread_len(vsread) == 0);
const unsigned int data[2] = {12, 25};
// Inserts void pointer to data to end of vsread_t
vsread_append(vsread, (void *) data);
vsread_append(vsread, (void *) (data + 1));
// Creates a one-time lock-free iterator based on vsread_t
vsread_iter_t * const iter = vsread_iter(vsread);
// Index changes as you iter through vsread_iter_t
assert(vsread_iter_index(iter) == 0);
// Clears vsread_t, doesn't change existing iterators
vsread_clear(vsread);
assert(vsread_len(vsread) == 0);
assert(vsread_iter_len(iter) == 2);
assert(*(unsigned int *) vsread_iter_next(iter) == 12);
assert(vsread_iter_index(iter) == 1);
assert(*(unsigned int *) vsread_iter_next(iter) == 25);
assert(vsread_iter_index(iter) == 2);
assert(vsread_iter_next(iter) == NULL);
assert(vsread_iter_index(iter) == 2);
assert(vsread_iter_len(iter) == 2);
// Never forget to free vsread_iter_t
vsread_iter_destroy(iter);
// Create updated vsread_iter_t
vsread_iter_t * const iter2 = vsread_iter(vsread);
assert(vsread_iter_len(iter2) == 0);
assert(vsread_iter_next(iter2) == NULL);
vsread_iter_destroy(iter2);
// Never forget to free vsread_t
vsread_destroy(vsread);
return 0;
}
```
### Multi thread C example (FFI)
```
#include<pthread.h>
#include<stdio.h>
#include "../include/voluntary_servitude.h"
const unsigned int num_producers = 4;
const unsigned int num_consumers = 8;
const unsigned int num_producer_values = 1000;
const unsigned int data[3] = {12, 25, 89};
void* producer();
void* consumer();
int main(int argc, char** argv)
{
// Rust allocates memory through malloc
vsread_t * const vsread = vsread_new();
unsigned int current_thread = 0;
pthread_attr_t attr;
pthread_t consumers[num_consumers],
producers[num_producers];
if (pthread_attr_init(&attr) != 0) {
fprintf(stderr, "Failed to initialize pthread arguments.\n");
exit(-1);
}
// Creates producer threads
for (current_thread = 0; current_thread < num_producers; ++current_thread) {
if (pthread_create(&producers[current_thread], &attr, &producer, (void *) vsread) != 0) {
fprintf(stderr, "Failed to create producer thread %d.\n", current_thread);
exit(-2);
}
}
// Creates consumers threads
for (current_thread = 0; current_thread < num_consumers; ++current_thread) {
if (pthread_create(&consumers[current_thread], &attr, &consumer, (void *) vsread) != 0) {
fprintf(stderr, "Failed to create consumer thread %d.\n", current_thread);
exit(-3);
}
}
// Join all threads, ensuring vsread_t* is not used anymore
for (current_thread = 0; current_thread < num_producers; ++current_thread) {
pthread_join(producers[current_thread], NULL);
}
for (current_thread = 0; current_thread < num_consumers; ++current_thread) {
pthread_join(consumers[current_thread], NULL);
}
// Never forget to free the memory allocated through rust
vsread_destroy(vsread);
(void) argc;
(void) argv;
return 0;
}
void * producer(void * const vsread){
unsigned int index;
for (index = 0; index < num_producer_values; ++index) {
vsread_append(vsread, (void *) (data + (index % 2)));
}
return NULL;
}
void * consumer(void * const vsread) {
const unsigned int total_values = num_producers * num_producer_values;
unsigned int values = 0;
while (values < total_values) {
unsigned int sum = (values = 0);
vsread_iter_t * const iter = vsread_iter(vsread);
const void * value;
while ((value = vsread_iter_next(iter)) != NULL) {
++values;
sum += *(unsigned int *) value;
}
printf("Consumer counts %d elements summing %d.\n", values, sum);
vsread_iter_destroy(iter);
}
return NULL;
}
```