PersistentVector, transients, polishing

.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+.idea
+packages
+.project
+local_pubspec_yaml
+pubspec.lock
+.idea
+*.swp
+build

AUTHORS

@@ -0,0 +1,7 @@
+Paul Brauner <[email protected]>
+Rafael Brandão <[email protected]>
+Jozef Brandys <[email protected]>
+Roman Hudec <[email protected]>
+Marian Hornak <[email protected]>
+Tomas Kulich <[email protected]>
+Matus Fedak <[email protected]>

LICENSE

@@ -1,3 +1,4 @@
+Copyright 2014, VacuumLabs.
 Copyright 2012, Google Inc. All rights reserved. Redistribution and
 use in source and binary forms, with or without modification, are
 permitted provided that the following conditions are met:

README.md

@@ -1,50 +1,76 @@
 # Efficient Persistent Data Structures
 
-[![Build Status](https://drone.io/github.com/polux/persistent/status.png)](https://drone.io/github.com/polux/persistent/latest)
+[![Build Status](https://drone.io/github.com/vacuumlabs/persistent/status.png)](https://drone.io/github.com/vacuumlabs/persistent/latest)
 
-Mostly efficient persistent maps and sets for now. Also option types.
+Check out [changes in 2.0 version!] (changes_2_0.md)
 
-"Persistent" means immutable here, not "saved on disk".
+Learn how you can use [transients] (transients.md)
 
-```dart
-import 'package:persistent/persistent.dart';
+Want to understand the code? Want to contribute? See [technical overview] (technical.md)
 
-main() {
-  final emptyMap = new PersistentMap<String,int>();
-  final m1 = emptyMap.insert('a', 1).insert('b', 2);
-  final m2 = new PersistentMap<String,int>.fromMap({'a': 3, 'c': 4});
+<!-- The project is forked from
+[polux/persistent](https://github.com/polux/persistent).
+-->
 
-  print(m1);  // {a: 1, b: 2}
-  print(m2);  // {c: 4, a: 3}
-  print(m1.lookup('a'));  // Option.some(1)
-  print(m1.lookup('c'));  // Option.none()
+## What are persistent data structures
+*Persistent* data structure is an immutable structure; the main difference with standard data structures is how you 'write' to them: instead of mutating
+the old structure, you create the new, independent, (slightly) modified copy of it. Typical examples of commonly used Persistent structures are String (in Java, Javascript, Python, Ruby) or Python's Tuple or Java's BigDecimal. [(Not only)](http://www.infoq.com/presentations/Value-Identity-State-Rich-Hickey) we believe such concept could be beneficial also for other data structures such as Maps, Lists/Vectors, Sets.
 
-  final m3 = m1.delete('a');
-  print(m1);  // {a: 1, b: 2}
-  print(m3);  // {b: 2}
+     var couple = new PMap.fromMap({'father': 'Homer', 'mother': 'Marge'});
+     // do not (and can not) modify couple anymore
+     var withChild = couple.assoc('boy', 'Bart');
+     print(couple); // {mother: Marge, father: Homer}
+     print(withChild); // {boy: Bart, mother: Marge, father: Homer}
 
-  final m4 = m1.union(m2, (n,m) => n + m);
-  print(m4);  // {c: 4, a: 4, b: 2}
+## Got it. And it is cool because...?
 
-  final m5 = m1.mapValues((n) => n + 1);
-  print(m5);  // {a: 2, b: 3}
+### It disallows unwanted side effects
+You know the story. Late in the evening, exhausted and frustrated you find out that some guy that implemented
 
-  final m6 = m1.adjust('a', (n) => n + 1);
-  print(m6);  // {a: 2, b: 2}
-}
-```
+     int ComputeResponseLength(Map responseMap) 
 
-## Try it!
+got a 'great' idea, that instead of just computing response length he also mutates responseMap in some tricky way (say, he does some kind of sanitization of responseMap). Even if this was mentioned in the documentation and even if the methods name was different: this is a spaghetti code.
 
-```
-git clone https://github.com/polux/persistent.git
-cd persistent
-pub install
-dart example/map_example.dart
-dart example/set_example.dart
-dart test/map_bench.dart
-```
+### Equality and hashCode done right
+Finally, they work as you'd expect. How cool is this:
 
-## More
+    // deeply persist the structure of Maps and Lists
+    PMap a = persist({[1,2]: 'tower', [1,3]: 'water'});
+    PMap b = persist({[1,2]: 'tower', [1,3]: 'water'});
+    assert(a==b); 
+    // kids, don't try this with standard List, it ain't going to work
+    print(a[persist([1, 2])]); // prints 'tower'
+
+### Instant 'deep copy'
+Just copy/pass the reference. It's like doing deep copy in O(1).
+
+### Caching made easier
+Caching can speed things up significantly. But how do you cache results of a function
+
+    List findSuspiciousEntries(List<Map> entries)
+
+One possible workaround would be to JSONize entries to string and use such string as a hashing key. However, it's much more elegant, safe (what about ordering of keys within maps?), performant and memory-wise with Persistent structures. Also, until you restrict to well-behaving functions, there's no need to invalidate cache; you can cache anything, for as long as you want.
+
+### Simplicity matters
+Fast copying or equality done right are nice features, but this is not the only selling point here. Having different ways how to copy (shallow, deep) objects or how to compare them (== vs. equals in Java) introduces new complexity. Even if you get used to it, it still takes some part of your mental capabilities and can lead to errors.
+
+### Structure sharing 
+    PMap map1 = persist({'a': 'something', 'b': bigMap});
+    PMap map2 = a.assoc('a', 'something completely different');
+Suppose you are interested, whether map1['b'] == map2['b']. Thanks to structure sharing, this is O(1) operation, which means it is amazingly fast - no need to traverse through the bigMap. Although it may sound unimportant at the first glance, it is what really enables fast caching of complex functions. Also, this is the reason, why [Om](https://github.com/swannodette/om/) framework is MUCH faster than Facebooks [React](http://facebook.github.io/react/).
+
+## And what is the prize for this all
+In the 2.0 release, we optimized memory consumption such that the only penalty for using Persistent
+comes at lower speed. Although structure sharing makes the whole thing much more effective than naive
+copy-it-all approach, Persistents are still slower than their mutable counterparts (note however, that on
+the other hand, some operations runs significantly faster, so its hard to say something conclusive
+here). Following numbers illustrate, how much slow are Persistent data structures when benchmarking either on DartVM
+or Dart2JS on Node (the numbers are quite independent of the structure size):
+
+* DartVM read speed: 2
+* DartVM write speed: 12 (5 by using Transients)
+* Dart2JS read speed: 3
+* Dart2JS write speed: 14 (6 by using Transients)
+
+Although the factors are quite big, the whole operation is still very fast and it probably won't be THE bottleneck which would slow down your app. 
 
-See [ImplementationDetails](https://github.com/polux/persistent/wiki/ImplementationDetails) and the [generated API documentation](http://polux.github.io/persistent/continuous/persistent/PersistentMap.html) for more information.

benchmark/.gitignore

@@ -0,0 +1,4 @@
+*.js
+*.js.map
+*.js.deps
+temp.out

benchmark/map_memory/makefile

@@ -0,0 +1,62 @@
+template_size = 1000
+
+define RUNNER
+function dartMainRunner(main, args){
+  main(process.argv.slice(2));
+}
+endef
+
+export RUNNER
+
+define INTRO
+- - - - - - - -
+Using (flat) map of size ${template_size}. Benchmark internally counts number of objects that fit
+into 1GB heap space. Output is in bytes per one key->value storage place. Instances of keys and
+values are shared between multiple copies of the structure we create, therefore their size do not
+affect the result (much). 
+- - - - - - - -
+endef
+
+export INTRO
+
+
+all: clean run
+
+
+build/map_memory.js: map_memory.dart
+	mkdir -p build
+	dart2js -o build/tmp.js map_memory.dart
+	cat ../preamble/d8.js >> build/map_memory.js
+	cat build/tmp.js >> build/map_memory.js
+	echo "$$RUNNER" >> build/map_memory.js
+
+clean:
+	rm -rf build
+
+
+run: build/map_memory.js
+
+	@echo "$$INTRO"
+
+#	@echo -n "DartVM persistent: "
+#	@dart --old_gen_heap_size=1024 map_memory.dart ${template_size} persistent > build/temp.out 2>/dev/null
+#	@tail -1 build/temp.out
+#
+#	@echo -n "DartVM map: "
+#	@dart --old_gen_heap_size=1024 map_memory.dart ${template_size} map > build/temp.out 2>/dev/null
+#	@tail -1 build/temp.out
+
+	@echo -n "NodeJS persistent: "
+	@ (! node --max-old-space-size=1024 build/map_memory.js ${template_size} persistent > build/temp.out) 2>/dev/null
+	@tail -1 build/temp.out
+
+	@echo -n "NodeJS map: "
+	@ (! node --max-old-space-size=1024 build/map_memory.js ${template_size} map > build/temp.out) 2>/dev/null
+	@tail -1 build/temp.out
+
+	@echo -n "NodeJS hashmap: "
+	@ (! node --max-old-space-size=1024 build/map_memory.js ${template_size} hashmap > build/temp.out) 2>/dev/null
+	@tail -1 build/temp.out
+
+	rm -f build/temp.out
+

benchmark/map_memory/map_memory.dart

@@ -0,0 +1,54 @@
+// Copyright (c) 2014, VacuumLabs.
+// Copyright (c) 2012, Google Inc. All rights reserved. Use of this source code
+// is governed by a BSD-style license that can be found in the LICENSE file.
+
+// Authors are listed in the AUTHORS file
+
+library map_memory;
+
+import 'package:vacuum_persistent/persistent.dart';
+import 'dart:collection';
+
+Map template = {};
+
+// here we will store the data to prevent it from garbage collection
+List data = [];
+
+var creators = {
+
+  "persistent": () => new PMap.fromMap(template),
+
+  "transient": (){
+    var res = new TMap();
+    template.forEach((k, v) => res.doAssoc(k, v));
+    return res;
+  },
+
+  "map": () => new Map.from(template),
+  "hashmap": () => new HashMap.from(template)
+};
+
+void run(int template_size, String mode) {
+
+  for (int i = 0; i < template_size; i++) {
+    template["$i".padLeft(8)] = "$i".padRight(8);
+  }
+
+  int allocated = 0;
+  for(bool go = true; go; allocated++){
+    try{
+      go = false;
+      var a = creators[mode]();
+      data.add(a);
+      go = true;
+      print(1073741824.0 / allocated / template_size);
+    } catch(e) {
+      data = null;
+    }
+  }
+}
+
+main(List<String> args){
+
+  run(int.parse(args[0]), args[1]);
+}