author: madmaxoft <github@xoft.cz> 2014-04-19 16:15:57 +0200
committer: madmaxoft <github@xoft.cz> 2014-04-19 16:15:57 +0200
commit: 62991d46fed9b5a7b181a2ef165935784d572b06 (patch)
tree: 6e8c5f2f8fad4fe0f9eb15d4d91a2d1ff0048ef0
parent: Fixed formatting, made function static. (diff)
download: cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar
cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.gz
cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.bz2
cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.lz
cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.xz
cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.zst
cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.zip
3 files changed, 195 insertions, 27 deletions
diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua
index 233bdbc46..45e8d9677 100644
--- a/MCServer/Plugins/APIDump/APIDesc.lua
+++ b/MCServer/Plugins/APIDump/APIDesc.lua
@@ -2929,9 +2929,10 @@ end
 	{
 		-- No sorting is provided for these, they will be output in the same order as defined here
 		{ FileName = "Writing-a-MCServer-plugin.html", Title = "Writing a MCServer plugin" },
-		{ FileName = "SettingUpDecoda.html", Title = "Setting up the Decoda Lua IDE" },
-		{ FileName = "SettingUpZeroBrane.html", Title = "Setting up the ZeroBrane Studio Lua IDE" },
-		{ FileName = "WebWorldThreads.html", Title = "Webserver vs World threads" },
+		{ FileName = "SettingUpDecoda.html",           Title = "Setting up the Decoda Lua IDE" },
+		{ FileName = "SettingUpZeroBrane.html",        Title = "Setting up the ZeroBrane Studio Lua IDE" },
+		{ FileName = "UsingChunkStays.html",           Title = "Using ChunkStays" },
+		{ FileName = "WebWorldThreads.html",           Title = "Webserver vs World threads" },
 	}
 } ;
 
diff --git a/MCServer/Plugins/APIDump/UsingChunkStays.html b/MCServer/Plugins/APIDump/UsingChunkStays.html
new file mode 100644
index 000000000..d3ecc6674
--- /dev/null
+++ b/MCServer/Plugins/APIDump/UsingChunkStays.html
@@ -0,0 +1,167 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<title>MCServer - Using ChunkStays</title>
+		<link rel="stylesheet" type="text/css" href="main.css" />
+		<link rel="stylesheet" type="text/css" href="prettify.css" />
+		<script src="prettify.js"></script>
+		<script src="lang-lua.js"></script>
+		<meta charset="UTF-8">
+	</head>
+	<body>
+		<div id="content">
+			<h1>Using ChunkStays</h1>
+			<p>
+			A plugin may need to manipulate data in arbitrary chunks, and it needs a way to make the server
+			guarantee that the chunks are available in memory.</p>
+			
+			<h2>The problem</h2>
+			<p>
+			Usually when plugins want to manipulate larger areas of world data, they need to make sure that the
+			server has the appropriate chunks loaded in the memory. When the data being manipulated can be further
+			away from the connected players, or the data is being manipulated from a console handler, there is a
+			real chance that the chunks are not loaded.</p>
+			<p>
+			This gets even more important when using the <a href="cBlockArea.html">cBlockArea</a> class for reading
+			and writing. Those functions will fail when any of the required chunks aren't valid. This means that
+			either the block area has incomplete data (Read() failed) or incomplete data has been written to the
+			world (Write() failed). Recovery from this is near impossible - you can't simply read or write again
+			later, because the world may have changed in the meantime.</p>
+			
+			<h2>The solution</h2>
+			<p>
+			The naive solution would be to monitor chunk loads and unloads, and postpone the operations until all
+			the chunks are available. This would be quite ineffective and also very soon it would become very
+			difficult to maintain, if there were multiple code paths requiring this handling.</p>
+			<p>
+			An alternate approach has been implemented, accessible through a single (somewhat hidden) function
+			call: <a href="cWorld.html">cWorld:ChunkStay()</a>. All that this call basically does is, it tells the
+			server "Load these chunks for me, and call this callback function once you have them all." And the
+			server does exactly that - it remembers the callback and asks the world loader / generator to provide
+			the chunks. Once the chunks become available, it calls the callback function for the plugin.</p>
+			<p>
+			There are a few gotcha-s, though. If the code that was requesting the read or write had access to some
+			of the volatile objects, such as <a href="cPlayer.html">cPlayer</a> or
+			<a href="cEntity.html">cEntity</a> objects, those cannot be accessed by the callback anymore, because
+			they may have become invalid in the meantime - the player may have disconnected, the entity may have
+			despawned. So the callback must use the longer way to access such objects, such as calling
+			<a href="cWorld.html">cWorld:DoWithEntityByID()</a> or
+			<a href="cWorld.html">cWorld:DoWithPlayer()</a>.</p>
+			
+			<h2>The example</h2>
+			<p>
+			As a simple example, consider a theoretical plugin that allows a player to save the immediate
+			surroundings of the spawn into a schematic file. The player issues a command to initiate the save, and
+			the plugin reads a 50 x 50 x 50 block area around the spawn into a cBlockArea and saves it on the disk
+			as "<PlayerName>_spawn.schematic". When it's done with the saving, it wants to send a message to the
+			player to let them know the command has succeeded.</p>
+			<p>
+			The first attempt shows the naive approach. It simply reads the block area and saves it, then sends the
+			message. I'll repeat once more, this code is <b>the wrong way</b> to do it!</p>
+<pre class="prettyprint lang-lua">
+function HandleCommandSaveSpawn(a_Split, a_Player)
+	-- Get the coords for the spawn:
+	local SpawnX = a_Player:GetWorld():GetSpawnX()
+	local SpawnY = a_Player:GetWorld():GetSpawnY()
+	local SpawnZ = a_Player:GetWorld():GetSpawnZ()
+	local Bounds = cCuboid(SpawnX - 25, SpawnY - 25, SpawnZ - 25, SpawnX + 25, SpawnY + 25, SpawnZ + 25)
+	Bounds:ClampY(0, 255)
+	
+	-- Read the area around spawn into a cBlockArea, save to file:
+	local Area = cBlockArea()
+	local FileName = a_Player:GetName() .. "_spawn.schematic"
+	Area:Read(a_Player:GetWorld(), Bounds, cBlockArea.baTypes + cBlockArea.baMetas)
+	Area:SaveToSchematicFile(FileName)
+	
+	-- Notify the player:
+	a_Player:SendMessage(cCompositeChat("The spawn has been saved", mtInfo))
+	return true
+end
+</pre>
+			<p>
+			Now if the player goes exploring far and uses the command to save their spawn, the chunks aren't
+			loaded, so the BlockArea reading fails, the BlockArea contains bad data. Note that the plugin fails to
+			do any error checking and if the area isn't read from the world, it happily saves the incomplete data
+			and says "hey, everything's right", althought it has just trashed any previous backup of the spawn
+			schematic with nonsense data.</p>
+			<hr/>
+			<p>
+			The following script uses the ChunkStay method to alleviate chunk-related problems. This is <b>the
+			right way</b> of doing it:</p>
+<pre class="prettyprint lang-lua">
+function HandleCommandSaveSpawn(a_Split, a_Player)
+	-- Get the coords for the spawn:
+	local SpawnX = a_Player:GetWorld():GetSpawnX()
+	local SpawnY = a_Player:GetWorld():GetSpawnY()
+	local SpawnZ = a_Player:GetWorld():GetSpawnZ()
+	local Bounds = cCuboid(SpawnX - 25, SpawnY - 25, SpawnZ - 25, SpawnX + 25, SpawnY + 25, SpawnZ + 25)
+	Bounds:ClampY(0, 255)
+	
+	-- Get a list of chunks that we need loaded:
+	local MinChunkX = math.floor((SpawnX - 25) / 16)
+	local MaxChunkX = math.ceil ((SpawnX + 25) / 16)
+	local MinChunkZ = math.floor((SpawnZ - 25) / 16)
+	local MaxChunkZ = math.ceil ((SpawnZ + 25) / 16)
+	local Chunks = {}
+	for x = MinChunkX, MaxChunkX do
+		for z = MinChunkZ, MaxChunkZ do
+			table.insert(Chunks, {x, z})
+		end
+	end  -- for x
+	
+	-- Store the player's name and world to use in the callback, because the a_Player object may no longer be valid:
+	local PlayerName = a_Player:GetName()
+	local World = a_Player:GetWorld()
+	
+	-- This is the callback that is executed once all the chunks are loaded:
+	local OnAllChunksAvailable = function()
+		-- Read the area around spawn into a cBlockArea, save to file:
+		local Area = cBlockArea()
+		local FileName = PlayerName .. "_spawn.schematic"
+		if (Area:Read(World, Bounds, cBlockArea.baTypes + cBlockArea.baMetas)) then
+			Area:SaveToSchematicFile(FileName)
+			Msg = cCompositeChat("The spawn has been saved", mtInfo)
+		else
+			Msg = cCompositeChat("Cannot save the spawn", mtFailure)
+		end
+		
+		-- Notify the player:
+		-- Note that we cannot use a_Player here, because it may no longer be valid (if the player disconnected before the command completes)
+		World:DoWithPlayer(PlayerName,
+			function (a_CBPlayer)
+				a_CBPlayer:SendMessage(Msg)
+			end
+		)
+	end
+	
+	-- Ask the server to load our chunks and notify us once it's done:
+	World:ChunkStay(Chunks, nil, OnAllChunksAvailable)
+	
+	-- Note that code here may get executed before the callback is called!
+	-- The ChunkStay says "once you have the chunks", not "wait until you have the chunks"
+	-- So you can't notify the player here, because the saving needn't have occurred yet.
+	
+	return true
+end
+</pre>
+			<p>
+			Note that this code does its error checking of the Area:Read() function, and it will not overwrite the
+			previous file unless it actually has the correct data. If you're wondering how the reading could fail
+			when we've got the chunks loaded, there's still the issue of free RAM - if the memory for the area
+			cannot be allocated, it cannot be read even with all the chunks present. So we still do need that
+			check.</p>
+			
+			<h2>The conclusion</h2>
+			<p>
+			Although it makes the code a little bit longer and is a bit more difficult to grasp at first, the
+			ChunkStay is a useful technique to add to your repertoire. It is to be used whenever you need access to
+			chunks that may potentially be inaccessible, and you really need the data.</p>
+			<p>Possibly the biggest hurdle in using the ChunkStay is the fact that it does its work in the
+			background, thus invalidating all cPlayer and cEntity objects your function may hold, so you need to
+			re-acquire them from their IDs and names. This is the penalty for using multi-threaded code.</p>
+			<script>
+				prettyPrint();
+			</script>
+		</div>
+	</body>
+</html>
diff --git a/MCServer/Plugins/APIDump/WebWorldThreads.html b/MCServer/Plugins/APIDump/WebWorldThreads.html
index fc80a6178..ee0b172e6 100644
--- a/MCServer/Plugins/APIDump/WebWorldThreads.html
+++ b/MCServer/Plugins/APIDump/WebWorldThreads.html
@@ -39,31 +39,31 @@
 
 			<h2>Example</h2>
 			The Core has the facility to kick players using the web interface. It used the following code for the kicking (inside the webadmin handler):
-			<pre class="prettyprint lang-lua">
-			local KickPlayerName = Request.Params["players-kick"]
-			local FoundPlayerCallback = function(Player)
-			  if (Player:GetName() == KickPlayerName) then
-				Player:GetClientHandle():Kick("You were kicked from the game!")
-			  end
+<pre class="prettyprint lang-lua">
+local KickPlayerName = Request.Params["players-kick"]
+local FoundPlayerCallback = function(Player)
+	if (Player:GetName() == KickPlayerName) then
+	Player:GetClientHandle():Kick("You were kicked from the game!")
+	end
+end
+cRoot:Get():FindAndDoWithPlayer(KickPlayerName, FoundPlayerCallback)
+</pre>
+The cRoot:FindAndDoWithPlayer() is unsafe and could have caused a deadlock. The new solution is queue a task; but since we don't know in which world the player is, we need to queue the task to all worlds:
+<pre class="prettyprint lang-lua">
+cRoot:Get():ForEachWorld(    -- For each world...
+	function(World)
+	World:QueueTask(         -- ... queue a task...
+		function(a_World)
+		a_World:DoWithPlayer(KickPlayerName,  -- ... to walk the playerlist...
+			function (a_Player)
+			a_Player:GetClientHandle():Kick("You were kicked from the game!")  -- ... and kick the player
 			end
-			cRoot:Get():FindAndDoWithPlayer(KickPlayerName, FoundPlayerCallback)
-			</pre>
-			The cRoot:FindAndDoWithPlayer() is unsafe and could have caused a deadlock. The new solution is queue a task; but since we don't know in which world the player is, we need to queue the task to all worlds:
-			<pre class="prettyprint lang-lua">
-			cRoot:Get():ForEachWorld(    -- For each world...
-			  function(World)
-				World:QueueTask(         -- ... queue a task...
-				  function(a_World)
-					a_World:DoWithPlayer(KickPlayerName,  -- ... to walk the playerlist...
-					  function (a_Player)
-						a_Player:GetClientHandle():Kick("You were kicked from the game!")  -- ... and kick the player
-					  end
-					)
-				  end
-				)
-			  end
-			)
-			</pre>
+		)
+		end
+	)
+	end
+)
+</pre>
 			<script>
 				prettyPrint();
 			</script>
author	madmaxoft <github@xoft.cz>	2014-04-19 16:15:57 +0200
committer	madmaxoft <github@xoft.cz>	2014-04-19 16:15:57 +0200
commit	62991d46fed9b5a7b181a2ef165935784d572b06 (patch)
tree	6e8c5f2f8fad4fe0f9eb15d4d91a2d1ff0048ef0
parent	Fixed formatting, made function static. (diff)
download	cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.gz cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.bz2 cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.lz cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.xz cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.tar.zst cuberite-62991d46fed9b5a7b181a2ef165935784d572b06.zip