From c1126ad38a1ca038c59008f3e3854b63d5e99f4d Mon Sep 17 00:00:00 2001
From: Jesse Boyd <boy0001@users.noreply.github.com>
Date: Tue, 1 Nov 2016 23:57:25 +1100
Subject: [PATCH] Created TaskBuilder (markdown)

---
 TaskBuilder.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 TaskBuilder.md

diff --git a/TaskBuilder.md b/TaskBuilder.md
new file mode 100644
index 0000000..db96389
--- /dev/null
+++ b/TaskBuilder.md
@@ -0,0 +1,57 @@
+### Overview
+The TaskBuilder simplifies creating sequential sync/async tasks.
+https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/util/task/TaskBuilder.java
+### Methods:
+ - sync([Runnable|ReturnTask|ReceiveTask|Task]) - Run a task on the main thread
+ - async([Runnable|ReturnTask|ReceiveTask|Task]) - Run a task off the main thread
+ - delay([int|DelayedTask]) - Delay the next task by a number of ticks
+ - syncParallel([Runnable|ReturnTask|ReceiveTask|Task]) - Run all the next syncParallel tasks in parallel
+ - asyncParallel([Runnable|ReturnTask|ReceiveTask|Task]) - Run all the next asyncParallel tasks in parallel
+ - syncWhenFree([SplitTask|ReturnTask|ReceiveTask|Task]) - Run a task when there's free time on the main thread
+ - abortIfTrue(Task<Boolean,Object>) - Abort all tasks if true
+ - build() - Starts execution
+ - buildAsync() - Starts execution from an async thread
+
+### Multiple tasks
+Just prints the number 6
+```Java
+new TaskBuilder()
+.async((ReturnTask<Integer>) () -> 5 + 1)
+.sync((ReceiveTask) input -> System.out.println(input))
+.build();
+```
+### SplitTask example
+```Java
+//In reality you'd use one of FAWE's async world manipulators (EditSession, AsyncWorld, FaweQueue etc.)
+// But this is just an example of how you can split up a task with the FAWE API
+
+final World world = Bukkit.getWorld("world");
+new TaskBuilder()
+.syncWhenFree(new TaskBuilder.SplitTask(20) { // Execution will be split into multiple 20ms tasks
+    @Override
+    public Object exec(Object previous) {
+        for (int x = 0; x < 100; x++) {
+            for (int y = 0; y < 100; y++) {
+                for (int z = 0; z < 100; z++) {
+                    world.getBlockAt(x, y, z).setType(Material.STONE);
+                    // FAWE will use this point to split the task
+                    split();
+                }
+            }
+        }
+        // We don't really need the result for any next tasks
+        return null;
+    }
+})
+.execute();
+```
+### Task meta
+The TaskBuilder extends Metadatable, so you can use it to store temporary data:
+https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/object/Metadatable.java
+```Java
+final TaskBuilder task = new TaskBuilder();
+task.sync(() -> {
+    task.setMeta("blah", 5);
+    return task.<Integer>getMeta("blah") + 56;
+});
+```
\ No newline at end of file