Merge pull request #4224 from markknol/patch-1

neko.vm documentation

std/neko/Random.hx

@@ -21,22 +21,37 @@
  */
 package neko;
 
+/**
+	A seeded pseudo-random generator.
+*/
 class Random {
 
 	var r : Dynamic;
 
+	/**
+		Create a new random with random seed.
+	*/
 	public function new() {
 		r = random_new();
 	}
 
+	/**
+		Set the generator seed.
+	*/
 	public function setSeed( s : Int ) {
 		random_set_seed(r,s);
 	}
 
+	/**
+		Return a random integer modulo max.
+	*/
 	public function int( max : Int ) : Int {
 		return random_int(r,max);
 	}
 
+	/**
+		Return a random float.
+	*/
 	public function float() : Float {
 		return random_float(r);
 	}
@@ -45,5 +60,4 @@ class Random {
 	static var random_set_seed = Lib.load("std","random_set_seed",2);
 	static var random_int = Lib.load("std","random_int",2);
 	static var random_float = Lib.load("std","random_float",1);
-
 }

std/neko/vm/Deque.hx

@@ -21,20 +21,41 @@
  */
 package neko.vm;
 
+/**
+	A message queue for multithread access.
+*/
 class Deque<T> {
 	var q : Dynamic;
+
+	/**
+		Create a message queue for multithread access.
+	*/
 	public function new() {
 		q = deque_create();
 	}
+
+	/**
+		Add a message at the end of the queue.
+	*/
 	public function add( i : T ) {
 		deque_add(q,i);
 	}
+
+	/**
+		Add a message at the head of the queue.
+	*/
 	public function push( i : T ) {
 		deque_push(q,i);
 	}
+
+	/**
+		Pop a message from the queue head. Either block until a message 
+		is available or return immediately with `null`.
+	*/
 	public function pop( block : Bool ) : Null<T> {
 		return deque_pop(q,block);
 	}
+
 	static var deque_create = neko.Lib.loadLazy("std","deque_create",0);
 	static var deque_add = neko.Lib.loadLazy("std","deque_add",2);
 	static var deque_push = neko.Lib.loadLazy("std","deque_push",2);

std/neko/vm/Gc.hx

@@ -21,17 +21,25 @@
  */
 package neko.vm;
 
+/**
+	Neko garbage collector utility.
+*/
 class Gc {
-
+	/**
+		Run the Neko garbage collector.
+	*/
 	public static function run( major : Bool ) {
 		_run(major);
 	}
 
+	/**
+		Return the size of the GC heap and the among of free space, 
+		in bytes.
+	*/
 	public static function stats() : { heap : Int, free : Int } {
 		return _stats();
 	}
 
 	static var _run = neko.Lib.load("std","run_gc",1);
 	static var _stats = neko.Lib.load("std","gc_stats",0);
-
 }

std/neko/vm/Lock.hx

@@ -23,15 +23,32 @@ package neko.vm;
 
 class Lock {
 	var l : Dynamic;
+
+	/**
+		Creates a lock which is initially locked.
+	*/
 	public function new() {
 		l = lock_create();
 	}
+
+	/**
+		Waits for a lock to be released and acquire it. If timeout 
+		(in seconds) is not `null` and expires then the returned 
+		value is `false`.
+	*/
 	public function wait( ?timeout : Float ) : Bool {
 		return lock_wait(l,timeout);
 	}
+	
+	/**
+		Release a lock. The thread does not need to own the lock 
+		to be able to release it. If a lock is released several 
+		times, it can be acquired as many times.
+	*/
 	public function release() {
 		lock_release(l);
 	}
+
 	static var lock_create = neko.Lib.load("std","lock_create",0);
 	static var lock_release = neko.Lib.load("std","lock_release",1);
 	static var lock_wait = neko.Lib.load("std","lock_wait",2);

std/neko/vm/Mutex.hx

@@ -21,20 +21,47 @@
  */
 package neko.vm;
 
+/**
+	Creates a mutex, which can be used to acquire a temporary lock 
+	to access some ressource. The main difference with a lock is 
+	that a mutex must always be released by the owner thread.
+*/
 class Mutex {
 	var m : Dynamic;
+
+	/**
+		Creates a mutex.
+	*/
 	public function new() {
 		m = mutex_create();
 	}
+
+	/**
+		The current thread acquire the mutex or wait if not available.
+		The same thread can acquire several times the same mutex but 
+		must release it as many times it has been acquired.
+	*/
 	public function acquire() {
 		mutex_acquire(m);
 	}
+
+	/**
+		Try to acquire the mutex, returns true if acquire or false 
+		if it's already locked by another thread.
+	*/
 	public function tryAcquire() : Bool {
 		return mutex_try(m);
 	}
+
+	/**
+		Release a mutex that has been acquired by the current thread. 
+		The behavior is undefined if the current thread does not own
+		the mutex.
+	*/
 	public function release() {
 		mutex_release(m);
 	}
+
 	static var mutex_create = neko.Lib.loadLazy("std","mutex_create",0);
 	static var mutex_release = neko.Lib.loadLazy("std","mutex_release",1);
 	static var mutex_acquire = neko.Lib.loadLazy("std","mutex_acquire",1);

std/neko/vm/Tls.hx

@@ -21,19 +21,34 @@
  */
 package neko.vm;
 
+/**
+	Creates thread local storage.
+*/
 class Tls<T> {
 
 	var t : Dynamic;
 	public var value(get,set) : T;
 
+	/**
+		Creates thread local storage. This is placeholder that can store
+		a value that will be different depending on the local thread. 
+		Set the tls value to `null` before exiting the thread 
+		or the memory will never be collected.
+	*/
 	public function new() {
 		t = tls_create();
 	}
 
+	/**
+		Returns the value set by tls_set for the local thread.
+	*/
 	function get_value() : T {
 		return tls_get(t);
 	}
 
+	/**
+		Set the value of the TLS for the local thread.
+	*/
 	function set_value( v : T ) {
 		tls_set(t,v);
 		return v;
@@ -42,5 +57,4 @@ class Tls<T> {
 	static var tls_create = neko.Lib.load("std","tls_create",0);
 	static var tls_get = neko.Lib.load("std","tls_get",1);
 	static var tls_set = neko.Lib.load("std","tls_set",2);
-
-}
+}

std/neko/vm/Ui.hx

@@ -21,20 +21,42 @@
  */
 package neko.vm;
 
+/**
+	Core native User Interface support. This API uses native WIN32 API 
+	on Windows, Carbon API on OSX, and GTK2 on Linux.
+*/
 class Ui {
 
+	/**
+		Tells if the current thread is the main loop thread or not. 
+		The main loop thread is the one in which the first "ui" 
+		library primitive has been loaded.
+	*/
 	public static function isMainThread() {
 		return _is_main_thread();
 	}
 
+	/**
+		Starts the native UI event loop. This method can only be called 
+		from the main thread.
+	*/
 	public static function loop() {
 		_loop();
 	}
 
+	/**
+		Stop the native UI event loop. This method can only be called 
+		from the main thread.
+	*/
 	public static function stopLoop() {
 		_sync(_stop_loop);
 	}
 
+	/**
+		Queue a method call callb to be executed by the main thread while 
+		running the UI event loop. This can be used to perform UI updates 
+		in the UI thread using results processed by another thread.
+	*/
 	public static function sync( f : Void -> Void ) {
 		_sync(f);
 	}
@@ -64,4 +86,4 @@ class Ui {
 	static var _stop_loop = neko.Lib.load("ui","ui_stop_loop",0);
 	static var _sync = neko.Lib.load("ui","ui_sync",1);
 
-}
+}