Page MenuHome GnuPG
Files F35313388

No OneTemporary
Actions

View Options

diff --git a/src/docs/article/command_execution.diviner b/src/docs/article/command_execution.diviner
index 92ace22..8d4b7d0 100644
--- a/src/docs/article/command_execution.diviner
+++ b/src/docs/article/command_execution.diviner
@@ -1,64 +1,64 @@
@title Command Execution
@group exec
This document describes best practices for executing system commands in PHP
using libphutil.
= Overview =
-PHP has several built-in mechanisms for executing system commands, like exec(),
-system(), and the backtick operator. However, these mechanisms often make it
-difficult to get all the information you need to handle error conditions,
-properly escaping commands is cumbersome, and they do not provide more advanced
-features like parallel execution and timeouts.
+PHP has several built-in mechanisms for executing system commands, like
+`exec()`, `system()`, and the backtick operator. However, these mechanisms
+often make it difficult to get all the information you need to handle error
+conditions, properly escaping commands is cumbersome, and they do not provide
+more advanced features like parallel execution and timeouts.
This document describes how to use the APIs in libphutil to execute commands
without encountering these problems.
-= Simple Commands: execx() and exec_manual() =
+= Simple Commands: `execx()` and `exec_manual()` =
-@{function:execx} and @{function:exec_manual} are replacements for exec(),
-system(), shell_exec(), and the backtick operator. The APIs look like this:
+@{function:execx} and @{function:exec_manual} are replacements for `exec()`,
+`system()`, `shell_exec()`, and the backtick operator. The APIs look like this:
list($stdout, $stderr) = execx('ls %s', $path);
list($err, $stdout, $stderr) = exec_manual('ls %s', $path);
-The major advantages of these methods over the exec() family are that you can
+The major advantages of these methods over the `exec()` family are that you can
easily check return codes, capture both stdout and stderr, and use a simple
-sprintf()-style formatting string to properly escape commands.
+`sprintf()`-style formatting string to properly escape commands.
@{function:execx} will throw a @{class:CommandException} if the command you
execute terminates with a nonzero exit code, while @{function:exec_manual}
returns the error code. If you use @{function:exec_manual}, you must manually
check the error code.
-= Advanced Commands: ExecFutures =
+= Advanced Commands: `ExecFutures` =
If you need more advanced features like parallel execution, command timeouts,
and asynchronous I/O, use @{class:ExecFuture}.
$future = new ExecFuture('ls %s', $path);
list($stdout, $stderr) = $future->resolvex();
@{class:ExecFuture} is a @{class:Future}, and can be used with constructs like
@{class:FutureIterator} to achieve and manage parallelism. See
@{article:Using Futures} for general information on how to use futures in
libphutil.
In addition to futures-based parallelism, you can set a timeout on an
-ExecFuture, which will kill the command if it takes longer than the specified
-number of seconds to execute:
+@{class:ExecFuture}, which will kill the command if it takes longer than the
+specified number of seconds to execute:
$future->setTimeout(30);
If the command runs longer than the timeout, the process will be killed and the
-future will resolve with a failure code (ExecFuture::TIMED_OUT_EXIT_CODE).
+future will resolve with a failure code (`ExecFuture::TIMED_OUT_EXIT_CODE`).
You can also write to the stdin of a process by using the
@{method:ExecFuture::write} method.
$future = new ExecFuture('bc');
$future->write('2+2');
list($stdout) = $future->resolvex();
See @{class:ExecFuture} for complete capability documentation.
diff --git a/src/docs/article/core_quick_reference.diviner b/src/docs/article/core_quick_reference.diviner
index 63dc012..9f14e2b 100644
--- a/src/docs/article/core_quick_reference.diviner
+++ b/src/docs/article/core_quick_reference.diviner
@@ -1,44 +1,45 @@
@title Core Utilities Quick Reference
@group util
Summary of libphutil core utilities.
= Overview =
This document provides a brief overview of the libphutil core utilities.
= Language Capabilities =
-Functions @{function:id}, @{function:head} and @{function:newv} address language
-grammar and implementation limitations.
+Functions @{function:id}, @{function:head} and @{function:newv} address
+language grammar and implementation limitations.
You can efficiently merge a vector of arrays with @{function:array_mergev}.
Functions @{function:head}, @{function:last}, @{function:head_key} and
@{function:last_key} let you access the first or last elements of an array
without raising warnings.
You can combine an array with itself safely with @{function:array_fuse}.
= Default Value Selection =
Functions @{function:idx}, @{function:nonempty} and @{function:coalesce} help
you to select default values when keys or parameters are missing or empty.
= Array and Object Manipulation =
Functions @{function:ipull}, @{function:igroup}, @{function:isort} and
@{function:ifilter} (**i** stands for **index**) simplify common data
manipulations applied to lists of arrays.
Functions @{function:mpull}, @{function:mgroup}, @{function:msort} and
@{function:mfilter} (**m** stands for **method**) provide the same capabilities
for lists of objects.
@{function:array_select_keys} allows you to choose or reorder keys from a
dictionary.
= Lunar Phases =
@{class:PhutilLunarPhase} calculates lunar phases, allowing you to harden an
-application against threats from werewolves, werebears, and other werecreatures.
+application against threats from werewolves, werebears, and other
+werecreatures.
diff --git a/src/docs/article/developing_xhpast.diviner b/src/docs/article/developing_xhpast.diviner
index 3357bb7..119cded 100644
--- a/src/docs/article/developing_xhpast.diviner
+++ b/src/docs/article/developing_xhpast.diviner
@@ -1,17 +1,17 @@
@title Developing XHPAST
@group xhpast
Instructions for developing XHPAST.
= XHPAST Development Builds =
-To develop XHPAST, you need to install flex and bison. These install out of most
-package systems, with the caveat that you need flex 2.3.35 (which is NEWER than
-flex 2.3.4) and some package systems don't have it yet. If this is the case
-for you, you can grab the source here:
+To develop XHPAST, you need to install flex and bison. These install out of
+most package systems, with the caveat that you need flex 2.3.35 (which is NEWER
+than flex 2.3.4) and some package systems don't have it yet. If this is the
+case for you, you can grab the source here:
http://flex.sourceforge.net/
-When building, run "make scanner parser all" instead of "make" to build the
+When building, run `make scanner parser all` instead of `make` to build the
entire toolchain. By default the scanner and parser are not rebuild, to avoid
requiring normal users to install flex and bison.
diff --git a/src/docs/article/overview.diviner b/src/docs/article/overview.diviner
index fd7ebf6..2933b8d 100644
--- a/src/docs/article/overview.diviner
+++ b/src/docs/article/overview.diviner
@@ -1,57 +1,57 @@
@title libphutil Overview
@group overview
This document provides a high-level introduction to libphutil.
= Overview =
**libphutil** (pronounced as "lib-futile", like the English word //futile//) is
a collection of PHP utility classes and functions. Most code in the library is
general-purpose, and makes it easier to build applications in PHP.
libphutil is principally the shared library for
[[ http://www.phabricator.org | Phabricator ]] and its CLI **Arcanist**, but is
suitable for inclusion in other projects. In particular, some of the classes
provided in this library vastly improve the state of common operations in PHP,
like executing system commands.
libphutil is developed and maintained by
[[ http://www.phacility.com/ | Phacility ]]. Some of the code in this library
was originally developed at Facebook, and parts of it appear in the core
libraries for <http://www.facebook.com/>.
= Loading libphutil =
To include libphutil in another project, include the
`src/__phutil_library_init__.php` file:
require_once 'path/to/libphutil/src/__phutil_library_init__.php';
This loads global functions and registers an autoload function with
`spl_autoload_register()`, so you can also use classes.
= Major Components =
Some of the major components of libphutil are:
- **Core Utilities**: a collection of useful functions like @{function:ipull}
- which simplify common data manipulation;
+ which simplify common data manipulation;
- **Filesystem**: classes like @{class:Filesystem} which provide a strict API
- for filesystem access and throw exceptions on failure, making it easier to
- write robust code which interacts with files;
+ for filesystem access and throw exceptions on failure, making it easier to
+ write robust code which interacts with files;
- **Command Execution**: libphutil provides a powerful system command
- primitive in @{class:ExecFuture} which makes it far easier to write
- command-line scripts which execute system commands
- (see @{article:Command Execution});
+ primitive in @{class:ExecFuture} which makes it far easier to write
+ command-line scripts which execute system commands
+ (see @{article:Command Execution});
- **@{function:xsprintf}**: allows you to define `sprintf()`-style functions
- which use custom conversions; and
- - **Library System**: an introspectable, inventoried system for organizing PHP
- code and managing dependencies, supported by static analysis.
+ which use custom conversions; and
+ - **Library System**: an introspectable, inventoried system for organizing
+ PHP code and managing dependencies, supported by static analysis.
= Extending and Contributing =
Information on extending and contributing to libphutil is available in the
Phabricator documentation:
- - to get started as a contributor, see @{article@phabcontrib:Contributor
+ - To get started as a contributor, see @{article@phabcontrib:Contributor
Introduction}.
diff --git a/src/docs/article/using_futures.diviner b/src/docs/article/using_futures.diviner
index 60ea373..5df4446 100644
--- a/src/docs/article/using_futures.diviner
+++ b/src/docs/article/using_futures.diviner
@@ -1,90 +1,90 @@
@title Using Futures
-@group futures
+@group future
Overview of how futures work in libphutil.
= Overview =
Futures (also called "Promises") are objects which represent the result of some
pending computation (like executing a command or making a request to another
server), but don't actually hold that result until the computation finishes.
They are used to simplify parallel programming, since you can pass the future
around as a representation for the real result while the real result is being
computed in the background. When the object is asked to return the actual
result, it blocks until the result is available.
libphutil provides a number of future-based APIs, as they strike a good balance
between ease of use and power for many of the domains where PHP is a reasonable
language choice.
Each type of future is used to do a different type of computation (for instance,
@{class:ExecFuture} executes system commands while @{class:HTTPFuture} executes
HTTP requests), but all of them behave in a basically similar way and can be
manipulated with the same top-level constructs.
= Basics =
You create a future by instantiating the relevant class and ask it to return the
result by calling `resolve()`:
- $gzip_future = new ExecFuture("gzip %s", $some_file);
+ $gzip_future = new ExecFuture('gzip %s', $some_file);
$gzip_future->start();
// The future is now executing in the background, and you can continue
// doing computation in this process by putting code here.
list($err, $stdout, $stderr) = $gzip_future->resolve();
When you call `resolve()`, the future blocks until the result is ready. You
can test if a future's result is ready by calling `isReady()`:
$is_ready = $gzip_future->isReady();
Being "ready" indicates that the future's computation has completed and it will
not need to block when you call `resolve()`.
Note that when you instantiate a future, it does not immediately initiate
computation. You must call `start()`, `isReady()` or `resolve()` to
activate it. If you simply call `resolve()` it will start, block until it is
complete, and then return the result, acting in a completely synchronous way.
See @{article:Command Execution} for more detailed documentation on how to
execute system commands with libphutil.
= Managing Multiple Futures =
Commonly, you may have many similar tasks you wish to parallelize: instead of
compressing one file, you want to compress several files. You can use the
@{class:FutureIterator} class to manage multiple futures.
$futures = array();
foreach ($files as $file) {
$futures[$file] = new ExecFuture("gzip %s", $file);
}
foreach (new FutureIterator($futures) as $file => $future) {
list($err, $stdout, $stderr) = $future->resolve();
if (!$err) {
echo "Compressed {$file}...\n";
} else {
echo "Failed to compress {$file}!\n";
}
}
@{class:FutureIterator} takes a list of futures and runs them in parallel,
**returning them in the order they resolve, NOT the original list order**. This
-allows your program to begin any followup computation as quickly as possible: if
-the slowest future in the list happens to be the first one, you can finish
+allows your program to begin any follow-up computation as quickly as possible:
+if the slowest future in the list happens to be the first one, you can finish
processing all the other futures while waiting for it.
You can also limit how many futures you want to run at once. For instance, to
process no more than 4 files simultaneously:
foreach (id(new FutureIterator($futures))->limit(4) as $file => $future) {
// ...
}
Consult the @{class:FutureIterator} documentation for detailed information on
class capabilities.
diff --git a/src/docs/book/libphutil.book b/src/docs/book/libphutil.book
index 9254efd..c37b91a 100644
--- a/src/docs/book/libphutil.book
+++ b/src/docs/book/libphutil.book
@@ -1,39 +1,87 @@
{
- "name" : "libphutil",
- "title" : "libphutil Technical Documentation",
- "short" : "libphutil Tech Docs",
- "preface" : "Technical documentation for developers using libphutil.",
- "root" : "../../../",
- "uri.source" :
+ "name": "libphutil",
+ "title": "libphutil Technical Documentation",
+ "short": "libphutil Tech Docs",
+ "preface": "Technical documentation for developers using libphutil.",
+ "root": "../../../",
+ "uri.source":
"https://secure.phabricator.com/diffusion/PHU/browse/master/%f$%l",
- "rules" : {
- "(\\.php$)" : "DivinerPHPAtomizer",
- "(\\.diviner$)" : "DivinerArticleAtomizer"
+ "rules": {
+ "(\\.diviner$)": "DivinerArticleAtomizer",
+ "(\\.php$)": "DivinerPHPAtomizer"
},
- "exclude" : [
+ "exclude": [
"(^externals/)",
+ "(^resources/)",
"(^scripts/)",
- "(^support/)",
- "(^resources/)"
+ "(^support/)"
],
- "groups" : {
- "overview" : {
- "name" : "libphutil Overview"
+ "groups": {
+ "overview": {
+ "name": "libphutil Overview"
},
- "util" : {
- "name" : "Core Utilities",
- "include": "(^src/utils/)"
+ "aphront": {
+ "name": "Aphront",
+ "include": "(^src/aphront/)"
+ },
+ "auth": {
+ "name": "Authentication",
+ "include": "(^src/auth/)"
+ },
+ "conduit": {
+ "name": "Conduit",
+ "include": "(^src/conduit/)"
+ },
+ "console": {
+ "name": "Console",
+ "include": "(^src/console/)"
+ },
+ "daemon": {
+ "name": "Daemons",
+ "include": "(^src/daemon/)"
+ },
+ "error": {
+ "name": "Errors",
+ "include": "(^src/error/)"
+ },
+ "filesystem": {
+ "name": "Filesystem",
+ "include": "(^src/filesystem/)"
},
- "library" : {
+ "future": {
+ "name": "Futures",
+ "include": "(^src/future/)"
+ },
+ "internationalization": {
+ "name": "Internationalization",
+ "include": "(^src/internationalization/)"
+ },
+ "lexer": {
+ "name": "Lexers",
+ "include": "(^src/lexer/)"
+ },
+ "library": {
"name": "libphutil Library System",
"include": "(^src/moduleutils/)"
},
- "auth" : {
- "name": "Authentication",
- "include": "(^src/auth/)"
+ "parser": {
+ "name": "Parsers",
+ "include": "(^src/parser/)"
},
- "utf8" : {
+ "phage": {
+ "name": "Phage",
+ "include": "(^src/phage/)"
+ },
+ "remarkup": {
+ "name": "Remarkup",
+ "include": "(^src/markup/)"
+ },
+ "utf8": {
"name": "Handling Unicode and UTF-8"
+ },
+ "util": {
+ "name": "Core Utilities",
+ "include": "(^src/utils/)"
}
}
}

File Metadata

Mime Type
text/x-diff
Expires
Thu, Feb 5, 9:28 PM (21 h, 45 m)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
f3/87/412d318cf401f6ba25389afe00e8

Event Timeline