Make database asynchronous

README.md

@@ -1,7 +1,7 @@
 ColdDB
 ===========
 
-ColdDB is a minetest mod that implements a serverless, NoSQL database engine.<br>
+ColdDB is a minetest mod that implements a serverless, asynchronous, NoSQL database engine.<br>
 It provides a key or key-value storage system using plain Lua tables. It also can iterate through the keys.<br>
 It is not required to add this mod to secure.trusted_mods this mod will still work.
 
@@ -27,16 +27,26 @@ colddb.set_key(coldbase,"MyKey")
 ```lua
 colddb.set(coldbase,"MyKeyAndValue","Hello world")
 ```
-5. retrieve items (get_key will return true, false, or nil)
+5. retrieve items (get_key's callback(arg) will return true, false, or nil)
 ```lua
-local key_and_value = colddb.get(coldbase,"MyKeyAndValue")
-local key = colddb.get_key(coldbase,"MyKey")
+colddb.get(coldbase,"MyKeyAndValue",nil,function(arg)
+	if arg then
+		minetest.log(string.format("value:%s",arg))
+	end
+end)
+colddb.get_key(coldbase,"MyKey",nil,function(arg)
+	if arg then
+		minetest.log("Found key")
+	else
+		minetest.log("Key not found")
+	end
+end)
 ```
 6. delete key(file) this function works on both keys and key-value keys.
 ```lua
 colddb.remove(coldbase,"MyKeyAndValue")
 ```
-7. if add_to_mem_pool is true(true by default). keys are stored in a lua table(memory) for 30 seconds or more depending on its use. This is to prevent the database from constantly loading up the data file.
+7. if add_to_mem_pool is true(true by default). keys are stored in a weak lua table(memory) it will be removed by the gc if its not in-use. Storing data in memory is to prevent the database from constantly loading up data from files.
 ```lua
 coldbase.add_to_mem_pool = true
 ```
@@ -48,9 +58,9 @@ coldbase.indexes = true
 ```lua
 colddb.get_count(coldbase)
 ```
-10. only if coldbase.indexes == true. iterates through the indexing file 50 times per game tick(breaks and ends if it reached the end of the file).
+10. only if coldbase.indexes == true. iterates through the indexing file(breaks and ends if it reached the end of the file).
 ```lua
-colddb.iterate_index_table(coldbase,nil,func_list_keys,nil,50)
+colddb.iterate_index_table(coldbase,nil,func_list_keys,nil)
 ```
 11. adds folders which can be used in other functions that have tag_name arg.
 ```lua
@@ -75,18 +85,14 @@ ip_db = colddb.get_db("watchlist")
 colddb.add_global_tag(ip_db,"ips")
 
 -- return a recorded ip address from the data base.
-function ip_db.find(player)
-	local f = colddb.get(ip_db,player)
-	if f then
-		return f
-	end
-	return nil
+function ip_db.find(player,callback)
+	colddb.get(ip_db,player,nil,callback)
 end
 
 -- Key is the file and file name. Value is the content's within the file.
 -- global tag(ips)--->key(Player name)--->value(ip address)
 function ip_db.record_ip(player,ip)
-	colddb.set(ip_db,player, ip)
+	colddb.set(ip_db,player,ip)
 end
 
 function ip_db.delete(player)
@@ -97,6 +103,23 @@ end
 minetest.register_on_prejoinplayer(function(name, ip)
 	ip_db.record_ip(name,ip)
 end)
+
+minetest.register_chatcommand("ip", {
+	params = "<player>",
+	description = "Get an player's ip address.",
+    func = function(name, param)
+		-- Get the ip record asynchronously.
+		colddb.get(ip_db,param,nil,function(record)
+			-- If record is contains data send it to the player.
+			if record then
+				minetest.chat_send_player(name,string.format("%s:%s",param,record))
+			else
+				-- No record was found.
+				minetest.chat_send_player(name,"Can not find ip record.")
+			end
+		end)
+    end
+})
 ```
 
 Quick Look Notes
@@ -126,7 +149,7 @@ API
   
   - **colddb.get_count(db,tag_name)**
   
-  - **colddb.iterate_index_table(db,begin_func,func_on_iterate,end_func,cycles_per_tick,args,tag_name)**
+  - **colddb.iterate_index_table(db,begin_func,func_on_iterate,end_func,args,tag_name)**
   
     - **begin_func(args)**
 	
@@ -138,9 +161,9 @@ API
   
   - **colddb.set_key(db,name,tag_name)**
   
-  - **colddb.get(db,name,tag_name)**
+  - **colddb.get(db,name,tag_name,callback(arg))**
   
-  - **colddb.get_key(db,name,tag_name)**
+  - **colddb.get_key(db,name,tag_name,callback(arg))**
   
   - **colddb.remove(db,name,tag_name)**