From ed227d1dd7a45c1e44e896ad9291fa1e12cfab06 Mon Sep 17 00:00:00 2001
From: Michael Wallner <mike@php.net>
Date: Mon, 22 Aug 2016 14:07:02 +0200
Subject: [PATCH] document x.1.0 changes

---
 pq/Connection.md             |  3 +-
 pq/Connection/: Changelog.md |  7 ++++
 pq/Connection/flush.md       | 64 ++++++++++++++++++++++++++++++++++++
 pq/Result.md                 |  2 ++
 pq/Result/: Changelog.md     |  5 +++
 5 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 pq/Connection/: Changelog.md
 create mode 100644 pq/Connection/flush.md
 create mode 100644 pq/Result/: Changelog.md

diff --git a/pq/Connection.md b/pq/Connection.md
index 4dd56ab..4f63c36 100644
--- a/pq/Connection.md
+++ b/pq/Connection.md
@@ -77,6 +77,8 @@ Negotiating environment-driven parameter settings.
   Connection character set.
 * public bool $unbuffered = FALSE  
   Whether to fetch [asynchronous](pq/Connection/: Asynchronous Usage) results in unbuffered mode, i.e. each row generates a distinct pq\Result.
+* public bool $nonblocking = FALSE  
+  Whether to set the underlying socket nonblocking, useful for asynchronous handling of writes. See also pq\Connection::flush().
 
 ### Connection Information:
 * public (readonly) string $db  
@@ -103,4 +105,3 @@ Negotiating environment-driven parameter settings.
   Default transaction readonlyness for futire pq\Transaction instances.
 * public bool $defaultTransactionDeferrable = FALSE  
   Default transaction deferrability for future pq\Transaction instances.
-  
diff --git a/pq/Connection/: Changelog.md b/pq/Connection/: Changelog.md
new file mode 100644
index 0000000..fe8abe7
--- /dev/null
+++ b/pq/Connection/: Changelog.md	
@@ -0,0 +1,7 @@
+# pq\Connection Changelog
+
+0. v1.1.0, v2.1.0
+	* Added properties:
+		* pq\Connection::$nonblocking
+	* Added methods:
+		* pq\Connection::flush()
diff --git a/pq/Connection/flush.md b/pq/Connection/flush.md
new file mode 100644
index 0000000..6a281d9
--- /dev/null
+++ b/pq/Connection/flush.md
@@ -0,0 +1,64 @@
+# bool pq\Connection::flush()
+
+Flush pending writes on the connection.
+Call after sending any command or data on a nonblocking connection.
+
+If it returns FALSE, wait for the socket to become read or write-ready.
+If it becomes write-ready, call pq\Connection::flush() again.
+If it becomes read-ready, call pq\Connection::poll(), then call pq\Connection::flush() again.
+Repeat until pq\Connection::flush() returns TRUE.
+
+> ***NOTE:***  
+> This method was added in v1.1.0, resp. v2.1.0.
+
+## Params:
+
+None.
+
+## Returns:
+
+* bool, whether everything has been flushed.
+
+## Throws:
+
+* pq\Connection\InvalidArgumentException
+* pq\Connection\RuntimeException when no asynchronous operation is active, or flushing failed
+
+## Example:
+
+	<?php
+	$c = new pq\Connection();
+	$c->nonblocking = true;
+
+	$c->execAsync("SELECT '".str_repeat("a", 6e7)."'", function($r) {
+		$r->fetchCol($s);
+		var_dump(strlen($s));
+	});
+
+	$flushed = $c->flush();
+	do {
+		while (!$flushed || $c->busy) {
+			$r = $c->busy ? [$c->socket] : null;
+			$w = !$flushed ?[$c->socket] : null;
+
+			if (stream_select($r, $w, $e, null)) {
+				if ($r) {
+					printf("P%d", $c->poll());
+				}
+				if ($w) {
+					printf("F%d", $flushed = $c->flush());
+				}
+			}
+		}
+		echo "\n";
+	} while ($c->getResult());
+	?>
+
+### Yields:
+
+	F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0
+	... (omitted)
+	F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F1P3P3P3P3P3P3P3P3
+	... (omitted)
+	P3P3P3P3P3P3P3P3P3P3P3P3P3P3
+	int(60000000)
diff --git a/pq/Result.md b/pq/Result.md
index af11174..9ad6238 100644
--- a/pq/Result.md
+++ b/pq/Result.md
@@ -71,6 +71,8 @@ See [Fetching Results](pq/Result/: Fetching Results) for a general overview.
   The number of fields in a single tuple of the result set.
 * public (readonly) int $affectedRows  
   The number of rows affected by a statement.
+* public (readonly) array $diag  
+  Error details. See [PQresultErrorField](https://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQRESULTERRORFIELD) docs.
 * public int $fetchType = pq\Result::FETCH_ARRAY  
   The [type of return value](pq/Result#Fetch.types:) the fetch methods should return when no fetch type argument was given. Defaults to pq\Connection::$defaultFetchType.
 * public int $autoConvert = pq\Result::CONV_ALL  
diff --git a/pq/Result/: Changelog.md b/pq/Result/: Changelog.md
new file mode 100644
index 0000000..b601a41
--- /dev/null
+++ b/pq/Result/: Changelog.md	
@@ -0,0 +1,5 @@
+# pq\Result Changelog
+
+0. v1.1.0, v2.1.0
+	* Added properties:
+		* pq\Result::$diag
-- 
2.30.2