diff --git a/reference/yar/book.xml b/reference/yar/book.xml index 90922f5bf838..f75320892348 100644 --- a/reference/yar/book.xml +++ b/reference/yar/book.xml @@ -1,5 +1,5 @@ - + @@ -8,11 +8,24 @@ &reftitle.intro; - - Yar is a RPC framework which aims to provide a simple and easy way to do - communication between PHP applications - It has the ability to concurrently call multiple remote services. - + + Yar (Yet another RPC framework) is a light, concurrent RPC framework + which aims to provide a simple and easy way to do communication + between PHP applications. It can also issue multiple calls to remote + services concurrently. + + + Yar is a native PHP extension rather than a userland library. It uses + a compact binary protocol over HTTP, HTTPS or TCP and ships with three + built-in packagers (php, json + and, when built with , + msgpack), so no extra packages or proxy processes + are required. + + + The protocol is language agnostic: compatible implementations exist + for C, Java and Lua. + &reference.yar.setup; diff --git a/reference/yar/configure.xml b/reference/yar/configure.xml index 200f001afc4d..66cc871b6625 100644 --- a/reference/yar/configure.xml +++ b/reference/yar/configure.xml @@ -1,14 +1,14 @@ - +
&reftitle.install; - + &pecl.info; &url.pecl.package;yar - - + +
diff --git a/reference/yar/constants.xml b/reference/yar/constants.xml index a6d826b63382..3845c58a289e 100644 --- a/reference/yar/constants.xml +++ b/reference/yar/constants.xml @@ -1,164 +1,316 @@ - + &reftitle.constants; &extension.constants; - - - - - YAR_VERSION - (string) - - - - - - - - - YAR_CLIENT_PROTOCOL_HTTP - (int) - - - - - - - - - YAR_OPT_PACKAGER - (int) - - - - - - - - - YAR_OPT_TIMEOUT - (int) - - - - - - - - - YAR_OPT_CONNECT_TIMEOUT - (int) - - - - - - - - - YAR_OPT_HEADER - (array) - - - - Since 2.0.4 - - - - - - YAR_PACKAGER_PHP - (string) - - - - - - - - - YAR_PACKAGER_JSON - (string) - - - - - - - - - YAR_ERR_OKEY - (int) - - - - - - - - - YAR_ERR_OUTPUT - (int) - - - - - - - - - YAR_ERR_TRANSPORT - (int) - - - - - - - - - YAR_ERR_REQUEST - (int) - - - - - - - - - YAR_ERR_PROTOCOL - (int) - - - - - - - - - YAR_ERR_PACKAGER - (int) - - - - - - - - - YAR_ERR_EXCEPTION - (int) - - - - - - - - + + + + YAR_VERSION + (string) + + + + The version of the Yar extension, e.g. + "2.4.0". + + + + + + YAR_HAS_MSGPACK + (int) + + + + 1 when Yar was built with + , otherwise + 0. + + + + + + YAR_CLIENT_PROTOCOL_HTTP + (int) + + + + Identifies the HTTP protocol, exposed through the read-only + _protocol property of + Yar_Client. + + + + + + YAR_CLIENT_PROTOCOL_TCP + (int) + + + + Identifies the TCP protocol, exposed through the read-only + _protocol property of + Yar_Client. + + + + + + YAR_CLIENT_PROTOCOL_UNIX + (int) + + + + Identifies the Unix socket protocol, exposed through the read-only + _protocol property of + Yar_Client. + + + + + + YAR_OPT_PACKAGER + (int) + + + + Client option to override the + yar.packager directive + for a single client. The value must be one of + php, json or + msgpack. + + + + + + YAR_OPT_PERSISTENT + (int) + + + + Client option to enable persistent connections. When set to a + truthy value, HTTP keep-alive is used so that repeated calls to + the same server reuse the connection for the rest of the PHP + request lifecycle. + + + + + + YAR_OPT_TIMEOUT + (int) + + + + Client option to override the + yar.timeout directive, in + milliseconds. + + + + + + YAR_OPT_CONNECT_TIMEOUT + (int) + + + + Client option to override the + yar.connect_timeout + directive, in milliseconds. + + + + + + YAR_OPT_HEADER + (int) + + + + Client option to add custom HTTP headers. The value must be an + array of strings like + "X-Custom: value". Only effective with the + HTTP and HTTPS protocols. Available as of Yar 2.0.4. + + + + + + YAR_OPT_RESOLVE + (int) + + + + Client option to override hostname resolution for HTTP calls. The + value must be an array of strings in the format + HOST:PORT:ADDRESS, following the curl + CURLOPT_RESOLVE syntax. Requires libcurl + >= 7.21.3. Available as of Yar 2.1.0. + + + + + + YAR_OPT_PROXY + (int) + + + + Client option to route HTTP calls through an HTTP proxy. The value + must be a string such as 127.0.0.1:8888. + Available as of Yar 2.2.0. + + + + + + YAR_OPT_PROVIDER + (int) + + + + Client option carrying the provider identity sent with every + request. The value must be a string of at most 32 bytes, which is + passed to the server-side __auth magic method. + Available as of Yar 2.3.0. + + + + + + YAR_OPT_TOKEN + (int) + + + + Client option carrying the authentication token sent with every + request. The value must be a string of at most 32 bytes, which is + passed to the server-side __auth magic method. + Available as of Yar 2.3.0. + + + + + + YAR_PACKAGER_PHP + (string) + + + + The identifier of the php packager, + "PHP". + + + + + + YAR_PACKAGER_JSON + (string) + + + + The identifier of the json packager, + "JSON". + + + + + + YAR_PACKAGER_MSGPACK + (string) + + + + The identifier of the msgpack packager, + "MSGPACK". + + + + + + YAR_ERR_OKEY + (int) + + + + No error; the request was processed successfully. + + + + + + YAR_ERR_PACKAGER + (int) + + + + A packager error, e.g. a body that could not be unpacked. + + + + + + YAR_ERR_PROTOCOL + (int) + + + + A protocol error, e.g. a malformed Yar header. + + + + + + YAR_ERR_REQUEST + (int) + + + + A request error, e.g. a call to an undefined or non-public + method. + + + + + + YAR_ERR_OUTPUT + (int) + + + + An output error, e.g. the server could not start its output + buffer. + + + + + + YAR_ERR_TRANSPORT + (int) + + + + A transport error, e.g. a connection failure or timeout. + + + + + + YAR_ERR_EXCEPTION + (int) + + + + The remote service threw an exception while processing the + request. + + + + + &reftitle.examples; @@ -23,7 +23,7 @@ class Operator { } /** - * Sub + * Sub */ public function sub($a, $b) { return $a - $b; @@ -54,7 +54,14 @@ $server->handle(); - Access the server in browser(GET request) + Access the server in browser (GET request) + + When a GET request is issued to the service URI, Yar renders an + information page listing every public method of the executor object + together with its doc comment. This is controlled by the + yar.expose_info + directive. + &example.outputs.similar; Yar Server Info @@ -69,28 +76,27 @@ $server->handle(); add(1, 2)); -/* call via call */ +/* call via call() */ var_dump($client->call("add", array(3, 2))); - -/* _add cannot be called */ +/* _add cannot be called: it is not public */ var_dump($client->_add(1, 2)); ?> ]]> &example.outputs.similar; - + - + @@ -99,16 +105,20 @@ PHP Fatal error: Uncaught exception 'Yar_Server_Exception' with message 'call t ]]> @@ -119,7 +129,26 @@ mul result: 4 sub result: 1 add result: 3 ]]> - + + + + + Yar TCP Client Example + + Besides HTTP, Yar_Client can talk to Yar + compatible servers over TCP or Unix sockets, for example a service + implemented with the Yar C framework. The remote server must + implement the same binary Yar protocol. + + +add(1, 2)); +?> +]]> + diff --git a/reference/yar/ini.xml b/reference/yar/ini.xml index a9704caa2e22..297fec1c0637 100644 --- a/reference/yar/ini.xml +++ b/reference/yar/ini.xml @@ -1,5 +1,5 @@ - +
&reftitle.runtime; @@ -18,9 +18,15 @@ - yar.packager - php - INI_SYSTEM + yar.connect_timeout + 1000 + INI_ALL + + + + yar.content_type + application/octet-stream + INI_ALL @@ -30,21 +36,27 @@ - yar.connect_timeout - 1000 - INI_ALL + yar.expose_info + On + INI_PERDIR - yar.timeout - 5000 + yar.packager + php + INI_PERDIR + + + + yar.ssl_verify + Off INI_ALL - yar.expose_info - On - INI_SYSTEM + yar.timeout + 5000 + INI_ALL @@ -56,59 +68,119 @@ - + - yar.packager + yar.connect_timeout + int + + + + Connect timeout in milliseconds for HTTP calls issued through + Yar_Client and + Yar_Concurrent_Client. + + + + This value is interpreted in milliseconds. Prior to Yar 1.2.1 it + was measured in seconds (the default was + 1). + + + + + + + yar.content_type string - - it could be php, json, and msgpack(require built with msgpack support) - + + The value of the Content-Type response header + sent by Yar_Server. Yar speaks a binary + protocol, so the default is + application/octet-stream. + yar.debug - string + bool - - - + + Enables debug mode. When on, Yar emits + E_WARNING messages with protocol-level + details for every request and response, prefixed with + [Debug Yar_Server] or + [Debug Yar_Client] and a timestamp. + - + - yar.connect_timeout - int + yar.expose_info + bool - - timeout in ms - + + Whether Yar_Server::handle outputs the + service information page for non-POST (usually GET) requests. + When this directive is off, such requests throw a + Yar_Server_Exception instead. + - + - yar.timeout - int + yar.packager + string - - timeout in ms - + + The default packager used to serialize request and response + bodies. Valid values are php (PHP + serialization), json, and + msgpack (only when Yar was built with + ). + + + When Yar is built with msgpack support, the default becomes + msgpack. + + + This value can be overridden per client with the + YAR_OPT_PACKAGER option. + - + - yar.expose_info + yar.ssl_verify bool - - whether expose the service info(when access the server via GET) - + + Whether to verify the TLS certificate of HTTPS servers. When on, + the curl transport sets + CURLOPT_SSL_VERIFYPEER and + CURLOPT_SSL_VERIFYHOST, and requests to + servers with invalid certificates fail. Off by default for + backward compatibility. Available as of Yar 2.4.0. + + + + + + yar.timeout + int + + + + Timeout in milliseconds for RPC calls issued by + Yar_Client and + Yar_Concurrent_Client. + diff --git a/reference/yar/setup.xml b/reference/yar/setup.xml index c457985112bb..7035e5a05bb1 100644 --- a/reference/yar/setup.xml +++ b/reference/yar/setup.xml @@ -1,35 +1,113 @@ - + &reftitle.setup;
&reftitle.required; - - if you want to use msgpack as packager, you need compile Yar by your self - with ./configure --enable-msgpack - + + The cURL library is required for the HTTP and HTTPS transports. The + TCP transport is implemented with plain sockets and needs no extra + library. + + + The JSON extension is required, + which is bundled with PHP and always available as of PHP 8.0.0. + + + To use the msgpack packager, the + msgpack extension + must be installed and Yar must be built with the + configure option. +
+
&reftitle.install; - + &pecl.moved; - - + + &pecl.info; &url.pecl.package;yar. + + + &pecl.windows.download.avail; + + + The source code is hosted on + GitHub. To build + the extension from source: + + + + + + The following configure options are available: + + + + + + + + Location of the cURL installation, if it is not found in the + default include paths. + + + + + + + + + + Enables the msgpack packager and makes the + msgpack extension an optional dependency. When + Yar is built with this option, the default value of + yar.packager becomes + msgpack. + + + + + + + + + + Uses Linux epoll instead of + select() for I/O multiplexing, available as of + Yar 2.1.2. This can improve + Yar_Concurrent_Client performance under + high concurrency. It only takes effect on Linux; on other + platforms it is silently ignored. + + + +
- + + + &reference.yar.ini; +
&reftitle.resources; - - - + + This extension does not define any resources. +
diff --git a/reference/yar/versions.xml b/reference/yar/versions.xml index 024744016081..7868cdcc7b9a 100644 --- a/reference/yar/versions.xml +++ b/reference/yar/versions.xml @@ -9,6 +9,7 @@ + diff --git a/reference/yar/yar-client-exception.xml b/reference/yar/yar-client-exception.xml index 8990fc0eeba2..f32f4cde6cd7 100644 --- a/reference/yar/yar-client-exception.xml +++ b/reference/yar/yar-client-exception.xml @@ -1,7 +1,7 @@ - + - + The Yar_Client_Exception class Yar_Client_Exception @@ -11,9 +11,12 @@
&reftitle.intro; - - - + + Base class of the exceptions thrown when a request fails before, + during or after reaching the remote service: a subclass is thrown + depending on where the failure occurred. The exception code is one of + the YAR_ERR_* constants. +
@@ -21,69 +24,30 @@ &reftitle.classsynopsis; - - Yar_Client_Exception + + + Yar_Client_Exception + - - - - Yar_Client_Exception - - - - extends - Exception - - - - &Properties; + + extends + Exception + + + &InheritedProperties; + - &Methods; - - - &InheritedMethods; - + + &InheritedMethods; + +
- - -
- &reftitle.properties; - - - message - - - - - - code - - - - - - file - - - - - - line - - - - - -
- - - &reference.yar.entities.yar-client-exception; diff --git a/reference/yar/yar-client-packager-exception.xml b/reference/yar/yar-client-packager-exception.xml index b97113bc1242..3c5fe3ae4a12 100644 --- a/reference/yar/yar-client-packager-exception.xml +++ b/reference/yar/yar-client-packager-exception.xml @@ -1,87 +1,44 @@ - + The Yar_Client_Packager_Exception class Yar_Client_Packager_Exception -
&reftitle.intro; - - - + + Thrown when the response body cannot be unpacked with the requested packager (exception code YAR_ERR_PACKAGER). +
-
&reftitle.classsynopsis; - - - Yar_Client_Packager_Exception - - - - - Yar_Client_Packager_Exception - + + + Yar_Client_Packager_Exception + - - extends - Yar_Client_Exception - - - - &Properties; + + extends + Yar_Client_Exception + + &InheritedProperties; + &InheritedMethods; - - - + + + -
- - -
- &reftitle.properties; - - - message - - - - - - code - - - - - - file - - - - - - line - - - - - -
- - - diff --git a/reference/yar/yar-client-protocol-exception.xml b/reference/yar/yar-client-protocol-exception.xml index 211b26f85c3f..b46ead86b12c 100644 --- a/reference/yar/yar-client-protocol-exception.xml +++ b/reference/yar/yar-client-protocol-exception.xml @@ -1,87 +1,44 @@ - + The Yar_Client_Protocol_Exception class Yar_Client_Protocol_Exception -
&reftitle.intro; - - - + + Thrown when the response from the RPC service violates the Yar protocol, for example an unsupported protocol address or a malformed response header (exception code YAR_ERR_PROTOCOL). +
-
&reftitle.classsynopsis; - - - Yar_Client_Protocol_Exception - - - - - Yar_Client_Protocol_Exception - + + + Yar_Client_Protocol_Exception + - - extends - Yar_Client_Exception - - - - &Properties; + + extends + Yar_Client_Exception + + &InheritedProperties; + &InheritedMethods; - - - + + + -
- - -
- &reftitle.properties; - - - message - - - - - - code - - - - - - file - - - - - - line - - - - - -
- - - diff --git a/reference/yar/yar-client-transport-exception.xml b/reference/yar/yar-client-transport-exception.xml index da189ecfac85..8b5679d6a235 100644 --- a/reference/yar/yar-client-transport-exception.xml +++ b/reference/yar/yar-client-transport-exception.xml @@ -1,87 +1,44 @@ - + The Yar_Client_Transport_Exception class Yar_Client_Transport_Exception -
&reftitle.intro; - - - + + Thrown when the connection to the RPC service fails: connection refused, timeout, or an empty response (exception code YAR_ERR_TRANSPORT). +
-
&reftitle.classsynopsis; - - - Yar_Client_Transport_Exception - - - - - Yar_Client_Transport_Exception - + + + Yar_Client_Transport_Exception + - - extends - Yar_Client_Exception - - - - &Properties; + + extends + Yar_Client_Exception + + &InheritedProperties; + &InheritedMethods; - - - + + + -
- - -
- &reftitle.properties; - - - message - - - - - - code - - - - - - file - - - - - - line - - - - - -
- - - diff --git a/reference/yar/yar-client.xml b/reference/yar/yar-client.xml index f1c9fccd376e..dca6d9d6393c 100644 --- a/reference/yar/yar-client.xml +++ b/reference/yar/yar-client.xml @@ -1,5 +1,5 @@ - + @@ -11,9 +11,11 @@
&reftitle.intro; - - - + + The client side of the Yar RPC framework. A client is bound to a + single service address; invoking any undefined method on it issues a + remote call with that method name and the given arguments. +
@@ -21,43 +23,41 @@ &reftitle.classsynopsis; - - Yar_Client + + + Yar_Client + - - - - Yar_Client - - - &Properties; protected + int _protocol protected + string _uri protected + arraynull _options protected + bool _running - &Methods; - + + -
&reftitle.properties; @@ -65,32 +65,45 @@ _protocol - + + Read-only. The protocol derived from the service address: one of + YAR_CLIENT_PROTOCOL_HTTP, + YAR_CLIENT_PROTOCOL_TCP or + YAR_CLIENT_PROTOCOL_UNIX. + _uri - + + Read-only. The service address the client was created with. + _options - + + Read-only. An &array; of the options set on this client, keyed by + the YAR_OPT_* constants, or &null; if none were + set. + _running - + + Read-only. Whether a call issued by this client is currently in + progress. +
- &reference.yar.entities.yar-client; diff --git a/reference/yar/yar-concurrent-client.xml b/reference/yar/yar-concurrent-client.xml index be9f615ef221..fa6dedb85ea7 100644 --- a/reference/yar/yar-concurrent-client.xml +++ b/reference/yar/yar-concurrent-client.xml @@ -1,5 +1,5 @@ - + @@ -11,9 +11,17 @@
&reftitle.intro; - - - + + A static helper that batches remote RPC calls. Calls registered with + Yar_Concurrent_Client::call are not sent + immediately; they are all dispatched together, in parallel, by + Yar_Concurrent_Client::loop. + + + + Only HTTP(S) services are supported for concurrent calls. + +
@@ -21,66 +29,18 @@ &reftitle.classsynopsis; - - Yar_Concurrent_Client - - - - - Yar_Concurrent_Client - - - - &Properties; - - static - _callstack - - - static - _callback - - - static - _error_callback - + + + Yar_Concurrent_Client + - &Methods; - + - - -
- &reftitle.properties; - - - _callstack - - - - - - _callback - - - - - - _error_callback - - - - - -
- - - &reference.yar.entities.yar-concurrent-client; diff --git a/reference/yar/yar-server-exception.xml b/reference/yar/yar-server-exception.xml index 5ff7056f6e41..c77aeeb170f6 100644 --- a/reference/yar/yar-server-exception.xml +++ b/reference/yar/yar-server-exception.xml @@ -1,7 +1,7 @@ - + - + The Yar_Server_Exception class Yar_Server_Exception @@ -11,10 +11,13 @@
&reftitle.intro; - - If service threw exceptions, A Yar_Server_Exception will be threw in - client side. - + + Thrown on the client side when the RPC request failed on the server. + If the remote service method itself threw an exception, its message, + code, file, line and class name are carried over, and + Yar_Server_Exception::getType returns the + class name of the original exception. +
@@ -22,79 +25,57 @@ &reftitle.classsynopsis; - - Yar_Server_Exception - - - - - Yar_Server_Exception - - - - extends - Exception - - - + + + Yar_Server_Exception + + + + extends + Exception + + &Properties; protected + string _type + "Yar_Exception_Server" - + &InheritedProperties; + + &Methods; - - - &InheritedMethods; - + + &InheritedMethods; + + -
&reftitle.properties; - - message - - - - - - code - - - - - - file - - - - - - line - - - - _type - + + The class name of the exception thrown by the remote service, or + "Yar_Exception_Server" if the error was not + caused by a userland exception. Read via + Yar_Server_Exception::getType. +
- &reference.yar.entities.yar-server-exception; diff --git a/reference/yar/yar-server-output-exception.xml b/reference/yar/yar-server-output-exception.xml index 60ab88fe49c0..37fb140c2b95 100644 --- a/reference/yar/yar-server-output-exception.xml +++ b/reference/yar/yar-server-output-exception.xml @@ -1,87 +1,44 @@ - + The Yar_Server_Output_Exception class Yar_Server_Output_Exception -
&reftitle.intro; - - - + + Thrown when the server cannot capture the output of the service method (exception code YAR_ERR_OUTPUT). +
-
&reftitle.classsynopsis; - - - Yar_Server_Output_Exception - - - - - Yar_Server_Output_Exception - + + + Yar_Server_Output_Exception + - - extends - Yar_Server_Exception - - - - &Properties; + + extends + Yar_Server_Exception + + &InheritedProperties; + &InheritedMethods; - - - + + + -
- - -
- &reftitle.properties; - - - message - - - - - - code - - - - - - file - - - - - - line - - - - - -
- - - diff --git a/reference/yar/yar-server-packager-exception.xml b/reference/yar/yar-server-packager-exception.xml index 73c36face366..192d4e519b4e 100644 --- a/reference/yar/yar-server-packager-exception.xml +++ b/reference/yar/yar-server-packager-exception.xml @@ -1,87 +1,44 @@ - + The Yar_Server_Packager_Exception class Yar_Server_Packager_Exception -
&reftitle.intro; - - - + + Thrown when the request body cannot be unpacked with the packager announced in the request (exception code YAR_ERR_PACKAGER). +
-
&reftitle.classsynopsis; - - - Yar_Server_Packager_Exception - - - - - Yar_Server_Packager_Exception - + + + Yar_Server_Packager_Exception + - - extends - Yar_Server_Exception - - - - &Properties; + + extends + Yar_Server_Exception + + &InheritedProperties; + &InheritedMethods; - - - + + + -
- - -
- &reftitle.properties; - - - message - - - - - - code - - - - - - file - - - - - - line - - - - - -
- - - diff --git a/reference/yar/yar-server-protocol-exception.xml b/reference/yar/yar-server-protocol-exception.xml index 0cfee3e49087..52d5aa9f6e4d 100644 --- a/reference/yar/yar-server-protocol-exception.xml +++ b/reference/yar/yar-server-protocol-exception.xml @@ -1,87 +1,44 @@ - + The Yar_Server_Protocol_Exception class Yar_Server_Protocol_Exception -
&reftitle.intro; - - - + + Thrown when the incoming request violates the Yar protocol, for example a malformed request header (exception code YAR_ERR_PROTOCOL). +
-
&reftitle.classsynopsis; - - - Yar_Server_Protocol_Exception - - - - - Yar_Server_Protocol_Exception - + + + Yar_Server_Protocol_Exception + - - extends - Yar_Server_Exception - - - - &Properties; + + extends + Yar_Server_Exception + + &InheritedProperties; + &InheritedMethods; - - - + + + -
- - -
- &reftitle.properties; - - - message - - - - - - code - - - - - - file - - - - - - line - - - - - -
- - - diff --git a/reference/yar/yar-server-request-exception.xml b/reference/yar/yar-server-request-exception.xml index f8c6660032f7..f2eae9ff66bf 100644 --- a/reference/yar/yar-server-request-exception.xml +++ b/reference/yar/yar-server-request-exception.xml @@ -1,87 +1,44 @@ - + The Yar_Server_Request_Exception class Yar_Server_Request_Exception -
&reftitle.intro; - - - + + Thrown when the requested remote method does not exist on the server object, or is not public (exception code YAR_ERR_REQUEST). +
-
&reftitle.classsynopsis; - - - Yar_Server_Request_Exception - - - - - Yar_Server_Request_Exception - + + + Yar_Server_Request_Exception + - - extends - Yar_Server_Exception - - - - &Properties; + + extends + Yar_Server_Exception + + &InheritedProperties; + &InheritedMethods; - - - + + + -
- - -
- &reftitle.properties; - - - message - - - - - - code - - - - - - file - - - - - - line - - - - - -
- - - diff --git a/reference/yar/yar-server.xml b/reference/yar/yar-server.xml index 5e805fa1a8a6..1a7f1eb61a2d 100644 --- a/reference/yar/yar-server.xml +++ b/reference/yar/yar-server.xml @@ -1,5 +1,5 @@ - + @@ -11,9 +11,11 @@
&reftitle.intro; - - - + + Wraps an object and exposes all of its public methods as a remote + service, served over HTTP by + Yar_Server::handle. +
@@ -21,31 +23,27 @@ &reftitle.classsynopsis; - - Yar_Server + + + Yar_Server + - - - - Yar_Server - - - &Properties; protected + object _executor + null - &Methods; - + + -
&reftitle.properties; @@ -53,14 +51,15 @@ _executor - + + The object whose public methods are exposed as RPC services. +
- &reference.yar.entities.yar-server; diff --git a/reference/yar/yar_client/call.xml b/reference/yar/yar_client/call.xml index 4b043c8849ab..702bfee10e0c 100644 --- a/reference/yar/yar_client/call.xml +++ b/reference/yar/yar_client/call.xml @@ -1,22 +1,28 @@ - + - Yar_Client::__call - Call service + Yar_Client::call + Call a remote service &reftitle.description; - - public voidYar_Client::__call + + public mixedYar_Client::call stringmethod - arrayparameters + arrayarguments - - Issue a call to remote RPC method. - + + Issues an RPC call to the remote method method. This + is exactly what happens when a non-existent method is invoked on a + Yar_Client object (see + Yar_Client::__call); + Yar_Client::call only exists so that remote + methods literally named call or + __call can still be reached. + @@ -25,17 +31,17 @@ method - - Remote RPC method name. - + + The name of the remote service method. + - parameters + arguments - - Parameters. - + + The list of arguments passed to the remote method. + @@ -43,38 +49,25 @@ &reftitle.returnvalues; - - - + + Returns the return value of the remote service method. + - - &reftitle.examples; - - <function>Yar_Client::__call</function> example - -some_method("parameter"); -?> -]]> - - &example.outputs.similar; - - - - + + &reftitle.errors; + + When the call method does not exist on the server + side, a Yar_Server_Request_Exception is + thrown. See Yar_Client::__call for the full + list of failures and their exception classes. + - &reftitle.seealso; + Yar_Client::__call Yar_Client::setOpt diff --git a/reference/yar/yar_client/construct.xml b/reference/yar/yar_client/construct.xml index c01994945626..003fc848a0f7 100644 --- a/reference/yar/yar_client/construct.xml +++ b/reference/yar/yar_client/construct.xml @@ -1,5 +1,5 @@ - + @@ -9,26 +9,40 @@ &reftitle.description; - + final public Yar_Client::__construct - stringurl - arrayoptions - - - Create a Yar_Client to a - Yar_Server. - + stringuri + arraynulloptionsnull + + + Creates a Yar_Client for the RPC service located + at uri. + &reftitle.parameters; - url + uri - - Yar Server URL. - + + Address of the RPC service. The protocol is derived from the scheme: + http:// and https:// select the + HTTP transport, tcp:// selects the TCP transport, + and unix:// selects the Unix socket transport. + + + + + options + + + An &array; of client options, keyed by the + YAR_OPT_* constants, equivalent to calling + Yar_Client::setOpt for each entry. Invalid + options are silently skipped. + @@ -36,31 +50,39 @@ &reftitle.returnvalues; - - Yar_Client instance. - + + A new Yar_Client instance. + + + + + &reftitle.errors; + + If the URI does not start with a supported scheme, a + Yar_Client_Protocol_Exception is thrown. + &reftitle.examples; - <function>Yar_Client::__construct</function> example + <methodname>Yar_Client::__construct</methodname> example 1000, + YAR_OPT_PACKAGER => "json", +]); ?> ]]> - &example.outputs.similar; - - - - &reftitle.seealso; diff --git a/reference/yar/yar_client/getopt.xml b/reference/yar/yar_client/getopt.xml new file mode 100644 index 000000000000..152194e02ef2 --- /dev/null +++ b/reference/yar/yar_client/getopt.xml @@ -0,0 +1,100 @@ + + + + + + Yar_Client::getOpt + Read a client option + + + + &reftitle.description; + + public mixedYar_Client::getOpt + intname + + + Returns the value previously set with + Yar_Client::setOpt, or with the + options parameter of + Yar_Client::__construct. + + + + + &reftitle.parameters; + + + name + + + One of the YAR_OPT_* constants, see + Yar_Client::setOpt. + + + + + + + + &reftitle.returnvalues; + + The option value, or &false; if the option has not been set on this + client or the option name is unknown. + + + + + &reftitle.examples; + + <methodname>Yar_Client::getOpt</methodname> example + +setOpt(YAR_OPT_TIMEOUT, 1000); + +var_dump($client->getOpt(YAR_OPT_TIMEOUT)); +var_dump($client->getOpt(YAR_OPT_PACKAGER)); +?> +]]> + + &example.outputs.similar; + + + + + + + + &reftitle.seealso; + + Yar_Client::setOpt + + + + + + diff --git a/reference/yar/yar_client/setopt.xml b/reference/yar/yar_client/setopt.xml index b574c2cab074..233f30b07020 100644 --- a/reference/yar/yar_client/setopt.xml +++ b/reference/yar/yar_client/setopt.xml @@ -1,22 +1,23 @@ - + Yar_Client::setOpt - Set calling contexts + Set client options &reftitle.description; - - public Yar_ClientfalseYar_Client::setOpt + + public Yar_ClientboolYar_Client::setOpt intname mixedvalue - - - + + Sets an option on the client. Options are evaluated when a call is + issued, so they can be changed between calls. + @@ -25,23 +26,29 @@ name - - it can be: - YAR_OPT_PACKAGER, - YAR_OPT_PERSISTENT (Need server support), - YAR_OPT_TIMEOUT, - YAR_OPT_CONNECT_TIMEOUT, - YAR_OPT_HEADER (as of 2.0.4), - YAR_OPT_PROXY (as of 2.2.0) - + + One of the YAR_OPT_* constants: + + + YAR_OPT_PACKAGER — a packager name: php, json or, when built with msgpack support, msgpack + YAR_OPT_PERSISTENT — a boolean persistent-connection flag (HTTP keep-alive) + YAR_OPT_TIMEOUT — a timeout in milliseconds, overriding yar.timeout + YAR_OPT_CONNECT_TIMEOUT — a connect timeout in milliseconds, overriding yar.connect_timeout + YAR_OPT_HEADER (as of 2.0.4) — an &array; of additional HTTP header lines + YAR_OPT_RESOLVE (as of 2.1.0) — an &array; of hostname resolution entries + YAR_OPT_PROXY (as of 2.2.0) — an HTTP proxy address + YAR_OPT_PROVIDER (as of 2.3.0) — the provider identity, up to 32 bytes + YAR_OPT_TOKEN (as of 2.3.0) — the authentication token, up to 32 bytes + value - - - + + The option value. An invalid value raises a warning and makes the call + return &false;. + @@ -49,50 +56,78 @@ &reftitle.returnvalues; - - Returns $this on success&return.falseforfailure;. - + + Returns the client object itself, allowing a fluent interface, or + &false; when the option name is unknown, the value is invalid, or the + option does not apply to the protocol the client was created with. + + + + + &reftitle.errors; + + Conditions that make the call return &false; also raise a warning: + + + + + YAR_OPT_HEADER, + YAR_OPT_RESOLVE and + YAR_OPT_PROXY only work with the HTTP protocol; + using them with a tcp:// or + unix:// client raises a warning. + + + + + YAR_OPT_RESOLVE additionally requires libcurl + >= 7.21.3. + + + + + Each option expects a specific value type (string, boolean, integer or + array), described on the + constants page. + + + &reftitle.examples; - <function>Yar_Client::setOpt</function> example + <methodname>Yar_Client::setOpt</methodname> example SetOpt(YAR_OPT_CONNECT_TIMEOUT, 1000); +/* Set timeout to 1s */ +$client->setOpt(YAR_OPT_TIMEOUT, 1000); -//Set packager to JSON -$client->SetOpt(YAR_OPT_PACKAGER, "json"); +/* Set packager to JSON */ +$client->setOpt(YAR_OPT_PACKAGER, "json"); -//Set Custom headers -$client->SetOpt(YAR_OPT_HEADER, array("hr1: val1", "hd2: val2")); +/* Set custom headers */ +$client->setOpt(YAR_OPT_HEADER, ["X-Api-Key: value"]); -// Set Http Proxy -$client->SetOpt(YAR_OPT_PROXY, "127.0.0.1:8888"); +/* Route through an HTTP proxy */ +$client->setOpt(YAR_OPT_PROXY, "127.0.0.1:8888"); /* call remote service */ $result = $client->some_method("parameter"); ?> ]]> - &example.outputs.similar; - - - - &reftitle.seealso; + Yar_Client::getOpt Yar_Client::__call diff --git a/reference/yar/yar_client_exception/gettype.xml b/reference/yar/yar_client_exception/gettype.xml index 356df121aff0..f7b4c050313b 100644 --- a/reference/yar/yar_client_exception/gettype.xml +++ b/reference/yar/yar_client_exception/gettype.xml @@ -1,5 +1,5 @@ - + @@ -9,13 +9,19 @@ &reftitle.description; - + public stringYar_Client_Exception::getType - - - + + Returns the type of the exception. Client-side exceptions are raised by + the client itself (transport failures, protocol errors and so on), so + the type is always the fixed string + "Yar_Exception_Client". Use + Exception::getCode to tell the individual + failure apart; the code is one of the YAR_ERR_* + constants. + @@ -25,38 +31,43 @@ &reftitle.returnvalues; - + Returns "Yar_Exception_Client". - + &reftitle.examples; - <function>Yar_Client_Exception::getType</function> example + <methodname>Yar_Client_Exception::getType</methodname> example some_method("parameter"); +} catch (Yar_Client_Exception $e) { + var_dump($e->getType()); + var_dump($e->getCode()); +} ?> ]]> &example.outputs.similar; - &reftitle.seealso; - Yaf_Server_Exception::getType + Yar_Server_Exception::getType diff --git a/reference/yar/yar_concurrent_client/call.xml b/reference/yar/yar_concurrent_client/call.xml index ef2e48603b8c..5611b3920d4b 100644 --- a/reference/yar/yar_concurrent_client/call.xml +++ b/reference/yar/yar_concurrent_client/call.xml @@ -1,5 +1,5 @@ - + @@ -9,19 +9,27 @@ &reftitle.description; - - public static intYar_Concurrent_Client::call + + public static intfalsenullYar_Concurrent_Client::call stringuri stringmethod - arrayparameters - callablecallback - callableerror_callback - arrayoptions + arraynullparametersnull + callablenullcallbacknull + callablenullerror_callbacknull + arraynulloptionsnull - - Register a RPC call, but won't sent it immediately, it will be send while - further call to Yar_Concurrent_Client::loop. - + + Registers a remote RPC call. The request is not sent immediately; all + registered calls are sent together by + Yar_Concurrent_Client::loop, and the responses + are handled as they arrive. + + + + Only HTTP and HTTPS URIs are supported. TCP and Unix socket transports + are not available for concurrent calls. + + @@ -30,40 +38,51 @@ uri - - The RPC server URI (HTTP, TCP). - + + Address of the RPC service, starting with + http:// or https://. + method - - Service name (aka the method name). - + + The name of the remote service method. + parameters - - Parameters. - + + The list of arguments passed to the remote method. + callback - - A function callback, which will be called while the response return. - + + A callable invoked when the response for this call + arrives, with two arguments: the response value, and a + callinfo &array; with the keys + sequence, uri and + method. If omitted, the + callback of + Yar_Concurrent_Client::loop is used. + error_callback - If this callback is set, then Yar will call this callback while error occurred. + A callable invoked when this call fails, with three + arguments: the error type (one of the YAR_ERR_* + codes), the error message, and the callinfo + &array;. If omitted, the error_callback of + Yar_Concurrent_Client::loop is used. @@ -71,8 +90,10 @@ options - An &array; of options. - See the constants list. + An &array; of client options, keyed by the + YAR_OPT_* constants, see + Yar_Client::setOpt. Applied to this call + only. @@ -82,7 +103,13 @@ &reftitle.returnvalues; - A unique ID, can be used to identified which call it is. + Returns the sequence number of the registered call, a unique ID + starting from 1 that identifies the call. Returns + &false; when the concurrent client is already inside + Yar_Concurrent_Client::loop or when the maximum + of 128 registered calls is reached; in both cases a + warning is raised. Returns &null; if the URI or method name is empty, or + the URI is not an HTTP(S) address, with a warning. @@ -105,23 +132,18 @@ function error_callback($type, $error, $callinfo) Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback"); -// If the callback is not specified callback in loop will be used +/* If the callback is not specified, the callback of loop() will be used */ Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters")); -// This server accept JSON packager +/* This server accepts the JSON packager */ Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_PACKAGER => "json")); -// Custom timeout -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT => 1)); +/* Custom timeout */ +Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT => 1000)); -// The requests are not sent yet +/* The requests are not sent yet */ ]]> - &example.outputs.similar; - - - @@ -130,8 +152,6 @@ Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters Yar_Concurrent_Client::loop Yar_Concurrent_Client::reset - Yar_Server::__construct - Yar_Server::handle diff --git a/reference/yar/yar_concurrent_client/loop.xml b/reference/yar/yar_concurrent_client/loop.xml index 544edc571cfd..ad4b5c5bafac 100644 --- a/reference/yar/yar_concurrent_client/loop.xml +++ b/reference/yar/yar_concurrent_client/loop.xml @@ -1,21 +1,25 @@ - + Yar_Concurrent_Client::loop - Send all calls + Send and wait for all registered calls &reftitle.description; - - public static boolYar_Concurrent_Client::loop - callablecallback - callableerror_callback + + public static boolnullYar_Concurrent_Client::loop + callablenullcallbacknull + callablenullerror_callbacknull + arraynulloptionsnull - Send all registered remote RPC calls. + Sends all calls registered with + Yar_Concurrent_Client::call in parallel and + blocks until every response has arrived and been handled. The call list + is emptied when this method returns. @@ -25,24 +29,34 @@ callback - - If this callback is set, then Yar will call this callback after all - calls are sent and before any response return, with a $callinfo NULL. - - - Then, if user didn't specify callback when registering concurrent call, - this callback will be used to handle response, otherwise, the callback - specified while registering will be used. - + + A callable used to handle responses for calls that were + registered without their own callback. Right after all requests have + been sent, it is additionally called once with two &null; arguments, + before any response arrives. + error_callback - - If this callback is set, then Yar will call this callback while error - occurred. - + + A callable used to handle errors for calls that were + registered without their own error callback. It receives three + arguments: the error type (one of the YAR_ERR_* + codes), the error message, and the callinfo + &array;. + + + + + options + + + An &array; of client options, keyed by the + YAR_OPT_* constants, applied to every registered + call that does not override them. + @@ -50,42 +64,41 @@ &reftitle.returnvalues; - - - + + Returns &true; when every registered call has been handled, or when no + calls have been registered at all. Returns &false; if the concurrent + client is already running inside another loop; in that case a warning is + raised. + &reftitle.examples; - <function>Yar_Concurrent_Client::loop</function> example + <methodname>Yar_Concurrent_Client::loop</methodname> example "json")); - //this server accept json packager -Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT=>1)); - //custom timeout -Yar_Concurrent_Client::loop("callback", "error_callback"); //send the requests, - //the error_callback is optional +/* if the callback is not specified, the callback of loop() will be used */ +Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters")); + +Yar_Concurrent_Client::loop("callback", "error_callback"); ?> ]]> @@ -93,27 +106,20 @@ Yar_Concurrent_Client::loop("callback", "error_callback"); //send the requests, - &reftitle.seealso; Yar_Concurrent_Client::call Yar_Concurrent_Client::reset - Yar_Server::__construct - Yar_Server::handle diff --git a/reference/yar/yar_concurrent_client/reset.xml b/reference/yar/yar_concurrent_client/reset.xml index 166470b800fe..1c3d160d55ad 100644 --- a/reference/yar/yar_concurrent_client/reset.xml +++ b/reference/yar/yar_concurrent_client/reset.xml @@ -1,5 +1,5 @@ - + @@ -9,13 +9,22 @@ &reftitle.description; - + public static boolYar_Concurrent_Client::reset - - Clean all registered calls - + + Discards all calls registered with + Yar_Concurrent_Client::call that have not been + sent yet. + + + + Yar_Concurrent_Client::loop empties the call + list automatically once it has finished, so reset is only needed to + abort a batch that was never sent. + + @@ -25,8 +34,11 @@ &reftitle.returnvalues; - - + + Returns &true;, or &false; when the concurrent client is currently inside + Yar_Concurrent_Client::loop, in which case an + E_WARNING-level error is raised. + @@ -35,13 +47,18 @@ <function>Yar_Concurrent_Client::reset</function> example ]]> - &example.outputs.similar; - - - @@ -50,8 +67,6 @@ Yar_Concurrent_Client::call Yar_Concurrent_Client::loop - Yar_Server::__construct - Yar_Server::handle diff --git a/reference/yar/yar_server/construct.xml b/reference/yar/yar_server/construct.xml index a1b6702bd6b0..1b2992cc7ba9 100644 --- a/reference/yar/yar_server/construct.xml +++ b/reference/yar/yar_server/construct.xml @@ -1,34 +1,35 @@ - + Yar_Server::__construct - Register a server + Create an RPC server &reftitle.description; - + final public Yar_Server::__construct - Objectobj - - - Set up a Yar HTTP RPC Server, All the public methods of $obj will be - register as a RPC service. - + objectexecutor + + + Creates a Yar HTTP RPC server. All public methods of + executor are registered as RPC services. + &reftitle.parameters; - obj + executor - - An Object, all public methods of its will be registered as RPC - services. - + + Any object whose public methods should be exposed as RPC + services. Protected and private methods, and methods whose name + starts with an underscore, are not exposed. + @@ -36,23 +37,23 @@ &reftitle.returnvalues; - + An instance of Yar_Server. - + &reftitle.examples; - <function>Yar_Server::__construct</function> example + <methodname>Yar_Server::__construct</methodname> example handle(); ?> ]]> - &example.outputs.similar; - - - - &reftitle.seealso; - - Yar_Server::handle - + + + Yar_Server::handle + + diff --git a/reference/yar/yar_server/handle.xml b/reference/yar/yar_server/handle.xml index b33e9dc8c6f0..03076e507d9f 100644 --- a/reference/yar/yar_server/handle.xml +++ b/reference/yar/yar_server/handle.xml @@ -1,28 +1,32 @@ - + Yar_Server::handle - Start RPC Server + Start the RPC server &reftitle.description; - - public bool Yar_Server::handle - + + public boolYar_Server::handle + - - Start a RPC HTTP server, and ready for accpet RPC requests. - - - Usual RPC calls will be issued as HTTP POST requests. If a HTTP GET - request is issued to the uri, the service information (commented section - above) will be printed on the page - - - + + Starts handling the incoming RPC request. + + + + Usual RPC calls are issued as HTTP POST requests. If an HTTP GET + request is issued instead, the service information page, generated + from the public methods and their doc comments of the executor + object, is printed. This behaviour can be disabled with the + yar.expose_info + directive, in which case a GET request throws a + Yar_Server_Exception. + + @@ -32,25 +36,97 @@ &reftitle.returnvalues; + + Returns &true;. + + + + + &reftitle.errors; - boolean + + <methodname>Yar_Server::handle</methodname> errors + + + + Condition + Exception + + + + + + The remote method threw an exception. + + + Yar_Server_Exception (with the + original class name in its _type property). + + + + + The remote method was not found or is not public. + + + Yar_Server_Request_Exception. + + + + + The request body could not be unpacked. + + + Yar_Server_Packager_Exception. + + + + + The request is malformed on the protocol level. + + + Yar_Server_Protocol_Exception. + + + + + The server output could not be captured. + + + Yar_Server_Output_Exception. + + + + + Authentication failed, or the info page was requested while + yar.expose_info is + off. + + + Yar_Server_Exception with code + YAR_ERR_FORBIDDEN. + + + + +
&reftitle.examples; - <function>Yar_Server::handle</function> example + <methodname>Yar_Server::handle</methodname> example handle(); ?> ]]> - &example.outputs.similar; - - - - &reftitle.seealso; - - Yar_Server::__construct - + + + Yar_Server::__construct + + diff --git a/reference/yar/yar_server_exception/gettype.xml b/reference/yar/yar_server_exception/gettype.xml index c40fde4d5585..3a0d8bcb38ea 100644 --- a/reference/yar/yar_server_exception/gettype.xml +++ b/reference/yar/yar_server_exception/gettype.xml @@ -1,5 +1,5 @@ - + @@ -9,13 +9,16 @@ &reftitle.description; - - public stringYar_Server_Exception::getType + + public stringintYar_Server_Exception::getType - - Get the exception original type threw by server - + + When a remote method throws an exception, the server embeds the original + exception in the response and the client re-throws it as a + Yar_Server_Exception. This method returns the + class name of that original exception. + @@ -25,19 +28,21 @@ &reftitle.returnvalues; - - string - + + The class name of the exception thrown by the remote service, or + "Yar_Exception_Server" when the server-side exception + carried no class name. + &reftitle.examples; - <function>Yar_Server_Exception::getType</function> example + <methodname>Yar_Server_Exception::getType</methodname> example handle(); ?> - -//Client.php +]]> + + +getType()); var_dump($e->getMessage()); } +?> ]]> &example.outputs.similar; @@ -72,11 +81,10 @@ string(6) "client" - &reftitle.seealso; - + Yar_Client_Exception::getType