Skip to content

Commit

Permalink
Cleaned up the client documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@rbotzer
rbotzer committed Dec 25, 2015
1 parent 739bd85 commit 9ec7ecf
Show file tree
Hide file tree
Showing 75 changed files with 935 additions and 678 deletions.
89 changes: 55 additions & 34 deletions doc/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@
# Overview

The Aerospike <a href="http://www.aerospike.com/docs/architecture/clients.html"
target="_doc">PHP client</a> enables your PHP application to work with an
<a href="http://www.aerospike.com/docs/architecture/distribution.html"
target="_doc">Aerospike cluster</a> as its
target="_doc">client</a> for PHP enables your application to work with an
Aerospike <a href="http://www.aerospike.com/docs/architecture/distribution.html"
target="_doc">cluster</a> as its
<a href="http://www.aerospike.com/docs/guide/kvs.html" target="_doc">key-value store</a>.

The <a href="http://www.aerospike.com/docs/architecture/data-model.html" target="_doc">Data Model</a>
document gives further details on how data is organized in the cluster.

## Client API
The Aerospike PHP client API is described in the following sections:
The client API is described in the following sections:

### [Runtime Configuration](aerospike_config.md)
### [Session Handler](aerospike_sessions.md)
Expand All @@ -25,39 +25,48 @@ The Aerospike PHP client API is described in the following sections:
### [Info Methods](apiref_info.md)
### [Large Data Type Methods](aerospike_ldt.md)

## Implementation Status
So far the *Runtime Configuration*, *Lifecycle and Connection Methods*, *Error*
*Handling and Logging Methods*, *Query and Scan Methods*, *User Defined Methods*
, *Admin Methods*, *Info Methods* and *Key-Value Methods* have been implemented.

The *Large Data Type Methods* are implemented as a PHP library.

We expect the specification of the PHP client to closely describe our next
release, including the unimplemented methods. However, it is possible that
some changes to the client spec will occur.

## Persistent Connections

Initializing the C-client to connect to a specified cluster is a costly
operation, so ideally the C-client should be reused for the multiple requests
made against the same PHP process (as is the case for mod_php and fastCGI).

The PHP developer can determine whether the Aerospike class constructor will
use persistent connections or not by way of an optional boolean argument.
After the first time Aerospike::__construct() is called within the process, the
extension will attempt to reuse the persistent connection.

When persistent connections are used the methods _reconnect()_ and _close()_ do
not actually close the connection. Those methods only apply to instances of
class Aerospike which use non-persistent connections.
## Configuration in a Web Server Context

Initializing the client to a cluster is a costly
operation, so ideally it should be reused for the multiple requests
that the same PHP process will handle (as is the case for mod\_php and fastCGI).

The developer can determine whether the constructor will
use persistent connections by way of an optional boolean argument.
After the first time Aerospike::\_\_construct() is called within the process, the
client will be stored for reuse by subsequent requests, if persistent connections
were indicated. With persistent connections, the methods _reconnect()_ and
_close()_ do not actually close the connection.

Each Aerospike client opens 2*N connections to the cluster, where N is the number
of nodes in that cluster, and a connection simply costs a file descriptor
on the server-side. Depending on the number of web servers and PHP processes on
each server, you may need to adjust the
[proto-fd-max](http://www.aerospike.com/docs/reference/configuration/#proto-fd-max)
server config parameter and the OS limits to account for the necessary number of
[file descriptors](http://www.aerospike.com/docs/operations/troubleshoot/startup/#not-enough-file-descriptors-error-in-log).
On the client side, the web server should be configured to reduce the frequency
in which new clients are created. Historically, the `max_requests` for mod\_php
and FPM was set low to combat memory leaks. PHP has been stable on memory for a
long while, so the correct configuration would be to have fewer processes, and
let each of them handle a high number of requests. This reduces the process
initialization overhead, and the overall number of connections on the web
server. Monitoring the memory consumption of the PHP processes allows the
`max_requests` to be raised safely to an efficient, stable value.

The client keeps track of changes at the server-side through a
[cluster tending](http://www.aerospike.com/docs/architecture/clustering.html)
thread. In a web server context, a single client can handle cluster tending and
share its state through a shared-memory segment. To enable shm cluster tending,
the developer can set the [`aerospike.shm.use`](aerospike_config.md) ini config
to `true`, or at the [constructor](aerospike_construct.md) through its config.

## Halting a Stream

Halting a _query()_ or _scan()_ result stream can be done by returning (an
explicit) boolean **false** from the callback. The extension will capture the
return value from the registered PHP callback, and pass it to the C-client.
The C-client will then close the sockets to the nodes involved in streaming
results, effectively halting it.
explicit) boolean **false** from the callback.
The client will then close the sockets to the nodes of the cluster, halting the
stream of records.

## Handling Unsupported Types

Expand Down Expand Up @@ -116,7 +125,19 @@ wrapped binary-string: string(10) "truncated"
The binary-string that was given to put() without a wrapper: trunc
```

## Implementation Status
So far the *Runtime Configuration*, *Lifecycle and Connection Methods*, *Error*
*Handling and Logging Methods*, *Query and Scan Methods*, *User Defined Methods*
, *Admin Methods*, *Info Methods* and *Key-Value Methods* have been implemented.

The *Large Data Type Methods* are implemented as a PHP library.

Aerospike 3.7.x compatible list operations and geospatial secondary index
queries will be implemented with a near-future release of the client.

PHP 5.3.3 - 5.6.x is supported by this client. A new PHP 7 compatible extension
is in progress.

## Further Reading

- [How does the Aerospike client find a node](https://discuss.aerospike.com/t/how-does-aerospike-client-find-a-node/706)
- [How would hash collisions be handled](https://discuss.aerospike.com/t/what-will-aerospike-do-if-hash-collision-for-a-key/779)
63 changes: 32 additions & 31 deletions doc/aerospike.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,5 @@

# The Aerospike class
The Aerospike PHP client API may be described as follows:

## Introduction

The main Aerospike class

```php

Expand All @@ -15,7 +10,7 @@ final class Aerospike
const POLICY_KEY_SEND; // also send, store, and get the actual (ns,set,key) with each record

// The generation policy can be set using OPT_POLICY_GEN to one of
const POLICY_GEN_IGNORE; // write a record, regardless of generation
const POLICY_GEN_IGNORE; // write a record, regardless of generation (default)
const POLICY_GEN_EQ; // write a record, ONLY if given value is equal to the current record generation
const POLICY_GEN_GT; // write a record, ONLY if given value is greater-than the current record generation

Expand All @@ -27,7 +22,7 @@ final class Aerospike
// behaving similar to an array in PHP. Setting
// OPT_POLICY_EXISTS with one of these values will overwrite this.
// POLICY_EXISTS_IGNORE (aka CREATE_OR_UPDATE) is the default value
const POLICY_EXISTS_IGNORE; // interleave bins of a record if it exists
const POLICY_EXISTS_IGNORE; // interleave bins of a record if it exists (default)
const POLICY_EXISTS_CREATE; // create a record ONLY if it DOES NOT exist
const POLICY_EXISTS_UPDATE; // update a record ONLY if it exists
const POLICY_EXISTS_REPLACE; // replace a record ONLY if it exists
Expand All @@ -44,35 +39,34 @@ final class Aerospike

// Determines a handler for writing values of unsupported type into bins
// Set OPT_SERIALIZER to one of the following:
const SERIALIZER_NONE;
const SERIALIZER_PHP; // default handler
const SERIALIZER_JSON;
const SERIALIZER_USER;
const SERIALIZER_NONE; // throw an error when serialization is required
const SERIALIZER_PHP; // use the PHP serialize/unserialize functions (default)
const SERIALIZER_USER; // use a user-defined serializer

// OPT_SCAN_PRIORITY can be set to one of the following:
const SCAN_PRIORITY_AUTO; //The cluster will auto adjust the scan priority
const SCAN_PRIORITY_LOW; //Low priority scan.
const SCAN_PRIORITY_MEDIUM; //Medium priority scan.
const SCAN_PRIORITY_HIGH; //High priority scan.
const SCAN_PRIORITY_AUTO; // the cluster will auto adjust the scan priority
const SCAN_PRIORITY_LOW; // low priority scan.
const SCAN_PRIORITY_MEDIUM; // medium priority scan.
const SCAN_PRIORITY_HIGH; // high priority scan.

// Options can be assigned values that modify default behavior
const OPT_CONNECT_TIMEOUT; // value in milliseconds, default: 1000
const OPT_READ_TIMEOUT; // value in milliseconds, default: 1000
const OPT_WRITE_TIMEOUT; // value in milliseconds, default: 1000
const OPT_CONNECT_TIMEOUT; // value in milliseconds (default: 1000)
const OPT_READ_TIMEOUT; // value in milliseconds (default: 1000)
const OPT_WRITE_TIMEOUT; // value in milliseconds (default: 1000)
const OPT_POLICY_RETRY; // set to a Aerospike::POLICY_RETRY_* value
const OPT_POLICY_EXISTS; // set to a Aerospike::POLICY_EXISTS_* value
const OPT_SERIALIZER; // set the unsupported type handler
const OPT_SCAN_PRIORITY; // set to a Aerospike::SCAN_PRIORITY_* value
const OPT_SCAN_PERCENTAGE; // integer value 1-100, default: 100
const OPT_SCAN_CONCURRENTLY; // boolean value, default: false
const OPT_SCAN_NOBINS; // boolean value, default: false
const OPT_SCAN_PERCENTAGE; // integer value 1-100 (default: 100)
const OPT_SCAN_CONCURRENTLY; // boolean value (default: false)
const OPT_SCAN_NOBINS; // boolean value (default: false)
const OPT_POLICY_KEY; // records store the digest unique ID, optionally also its (ns,set,key) inputs
const OPT_POLICY_GEN; // set to array( Aerospike::POLICY_GEN_* [, $gen_value ] )
const OPT_POLICY_REPLICA; // set to one of Aerospike::POLICY_REPLICA_*
const OPT_POLICY_CONSISTENCY; // set to one of Aerospike::POLICY_CONSISTENCY_*
const OPT_POLICY_COMMIT_LEVEL;// set to one of Aerospike::POLICY_COMMIT_LEVEL_*
const OPT_TTL; // record ttl, value in seconds
const USE_BATCH_DIRECT; // batch-direct or batch-index protocol. default: 0
const USE_BATCH_DIRECT; // batch-direct or batch-index protocol (default: 0)

// Aerospike Status Codes:
//
Expand Down Expand Up @@ -145,11 +139,16 @@ final class Aerospike
const ERR_NOT_AUTHENTICATED;
const ERR_ROLE_VIOLATION;

// Status values returned by scanInfo()
const SCAN_STATUS_UNDEF; // Scan status is undefined.
const SCAN_STATUS_INPROGRESS; // Scan is currently running.
const SCAN_STATUS_ABORTED; // Scan was aborted due to failure or the user.
const SCAN_STATUS_COMPLETED; // Scan completed successfully.
// Status values returned by scanInfo(). Deprecated in favor of jobInfo()
const SCAN_STATUS_UNDEF; // scan status is undefined. deprecated.
const SCAN_STATUS_INPROGRESS; // scan is currently running. deprecated.
const SCAN_STATUS_ABORTED; // scan was aborted due to failure or the user. deprecated.
const SCAN_STATUS_COMPLETED; // scan completed successfully. deprecated.

// Status values returned by jobInfo()
const STATUS_UNDEF; // the job's status is undefined.
const STATUS_INPROGRESS; // the job is currently running.
const STATUS_COMPLETED; // the job completed successfully.

// Logger
const LOG_LEVEL_OFF ;
Expand Down Expand Up @@ -238,7 +237,9 @@ final class Aerospike
public int apply ( array $key, string $module, string $function[, array $args [, mixed &$returned [, array $options ]]] )
public int aggregate ( string $ns, string $set, array $where, string $module, string $function, array $args, mixed &$returned [, array $options ] )
public int scanApply ( string $ns, string $set, string $module, string $function, array $args, int &$scan_id [, array $options ] )
public int scanInfo ( integer $scan_id, array &$info [, array $options ] )
public int queryApply ( string $ns, string $set, array $where, string $module, string $function, array $args, int &$job_id [, array $options ] )
public int jobInfo ( integer $job_id, array &$info [, array $options ] )
public int scanInfo ( integer $scan_id, array &$info [, array $options ] ) // DEPRECATED. use jobInfo()

// query and scan methods
public int query ( string $ns, string $set, array $where, callback $record_cb [, array $select [, array $options ]] )
Expand All @@ -251,7 +252,6 @@ final class Aerospike
// admin methods
public int addIndex ( string $ns, string $set, string $bin, string $name, int $index_type, int $data_type [, array $options ] )
public int dropIndex ( string $ns, string $name [, array $options ] )
public int createIndex ( string $ns, string $set, string $bin, int $type, string $name ) // deprecated

// info methods
public int info ( string $request, string &$response [, array $host [, array $options ] ] )
Expand Down Expand Up @@ -288,5 +288,6 @@ final class Aerospike
### [Large Data Type Methods](aerospike_ldt.md)
### [Security Methods](apiref_security.md)

An overview of the development of the client is at the top level
[README](README.md).
## Further Reading

- [Client Overview](README.md)
24 changes: 12 additions & 12 deletions doc/aerospike_addindex.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ a namespace *ns*, *set* and *bin* with a specified *name*.

**name** the name of the index

**index_type** one of *Aerospike::INDEX_TYPE_\** .
**index_type** one of *Aerospike::INDEX\_TYPE\_\** .

**data_type** one of *Aerospike::INDEX_NUMERIC* and *Aerospike::INDEX_STRING*
**data_type** one of *Aerospike::INDEX\_NUMERIC* and *Aerospike::INDEX_STRING*

**options** including
- **Aerospike::OPT_WRITE_TIMEOUT**
Expand All @@ -40,26 +40,26 @@ constants. When non-zero the **Aerospike::error()** and
```php
<?php

$config = array("hosts"=>array(array("addr"=>"localhost", "port"=>3000)));
$db = new Aerospike($config);
if (!$db->isConnected()) {
echo "Aerospike failed to connect[{$db->errorno()}]: {$db->error()}\n";
$config = ["hosts" => [["addr"=>"localhost", "port"=>3000]]];
$client = new Aerospike($config);
if (!$client->isConnected()) {
echo "Aerospike failed to connect[{$client->errorno()}]: {$client->error()}\n";
exit(1);
}

$status = $db->addIndex("test", "user", "email", "user_email_idx", Aerospike::INDEX_TYPE_DEFAULT, Aerospike::INDEX_STRING);
$status = $client->addIndex("test", "user", "email", "user_email_idx", Aerospike::INDEX_TYPE_DEFAULT, Aerospike::INDEX_STRING);
if ($status == Aerospike::OK) {
echo "Index user_email_idx created on test.user.email\n";
else if ($status == Aerospike::ERR_INDEX_FOUND) {
echo "This index has already been created.\n";
} else {
echo "[{$db->errorno()}] ".$db->error();
echo "[{$client->errorno()}] ".$client->error();
}

$db->addIndex("test", "user", "movies", "user_movie_titles_idx", Aerospike::INDEX_TYPE_MAPKEYS, Aerospike::INDEX_STRING);
$db->addIndex("test", "user", "movies", "user_movie_views_idx", Aerospike::INDEX_TYPE_MAPVALUES, Aerospike::INDEX_NUMERIC);
$db->addIndex("test", "user", "aliases", "user_aliases_idx", Aerospike::INDEX_TYPE_LIST, Aerospike::INDEX_STRING);

$client->addIndex("test", "user", "movies", "user_movie_titles_idx", Aerospike::INDEX_TYPE_MAPKEYS, Aerospike::INDEX_STRING);
$client->addIndex("test", "user", "movies", "user_movie_views_idx", Aerospike::INDEX_TYPE_MAPVALUES, Aerospike::INDEX_NUMERIC);
$client->addIndex("test", "user", "aliases", "user_aliases_idx", Aerospike::INDEX_TYPE_LIST, Aerospike::INDEX_STRING);
$client->close();
?>
```

18 changes: 9 additions & 9 deletions doc/aerospike_aggregate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,12 @@ Currently the only UDF language supported is Lua. See the
Array:
bin => bin name
op => one of Aerospike::OP_EQ, Aerospike::OP_BETWEEN
val => scalar integer/string for OP_EQ or array($min, $max) for OP_BETWEEN
val => scalar integer/string for OP_EQ or [$min, $max] for OP_BETWEEN
```
*examples:*
```
array("bin"=>"name", "op"=>Aerospike::OP_EQ, "val"=>"foo")
array("bin"=>"age", "op"=>Aerospike::OP_BETWEEN, "val"=>array(35,50))
["bin"=>"name", "op"=>Aerospike::OP_EQ, "val"=>"foo"]
["bin"=>"age", "op"=>Aerospike::OP_BETWEEN, "val"=>[35,50]]
```

**module** the name of the UDF module registered against the Aerospike DB.
Expand Down Expand Up @@ -114,21 +114,21 @@ end
```php
<?php

$config = array("hosts"=>array(array("addr"=>"localhost", "port"=>3000)));
$db = new Aerospike($config);
if (!$db->isConnected()) {
echo "Aerospike failed to connect[{$db->errorno()}]: {$db->error()}\n";
$config = ["hosts" => [["addr"=>"localhost", "port"=>3000]]];
$client = new Aerospike($config);
if (!$client->isConnected()) {
echo "Aerospike failed to connect[{$client->errorno()}]: {$client->error()}\n";
exit(1);
}

// assuming test.users has a bin first_name, show the first name distribution
// for users in their twenties
$where = Aerospike::predicateBetween("age", 20, 29);
$status = $db->aggregate("test", "users", $where, "stream_udf", "group_count", array("first_name"), $names);
$status = $client->aggregate("test", "users", $where, "stream_udf", "group_count", ["first_name"], $names);
if ($status == Aerospike::OK) {
var_dump($names);
} else {
echo "An error occured while running the AGGREGATE [{$db->errorno()}] ".$db->error();
echo "An error occured while running the AGGREGATE [{$client->errorno()}] ".$client->error();
}

?>
Expand Down
16 changes: 8 additions & 8 deletions doc/aerospike_append.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,20 +43,20 @@ constants. When non-zero the **Aerospike::error()** and
```php
<?php

$config = array("hosts"=>array(array("addr"=>"localhost", "port"=>3000)));
$db = new Aerospike($config);
if (!$db->isConnected()) {
echo "Aerospike failed to connect[{$db->errorno()}]: {$db->error()}\n";
$config = ["hosts" => [["addr"=>"localhost", "port"=>3000]], "shm"=>[]];
$client = new Aerospike($config, true);
if (!$client->isConnected()) {
echo "Aerospike failed to connect[{$client->errorno()}]: {$client->error()}\n";
exit(1);
}

$key = $db->initKey("test", "users", 1234);
$options = array(Aerospike::OPT_TTL => 3600);
$status = $db->append($key, 'name', ' Ph.D.', $options);
$key = $client->initKey("test", "users", 1234);
$options = [Aerospike::OPT_TTL => 3600];
$status = $client->append($key, 'name', ' Ph.D.', $options);
if ($status == Aerospike::OK) {
echo "Added the Ph.D. suffix to the user.\n";
} else {
echo "[{$db->errorno()}] ".$db->error();
echo "[{$client->errorno()}] ".$client->error();
}

?>
Expand Down
Loading

0 comments on commit 9ec7ecf

Please sign in to comment.