previous next

Tutorial - scache_iov

Scache_iov is function to issue multiple operations on single request packet. While accessing scached locally is fast, doing multiple requests over network will be drastically slower. However scached's philosophy is to spur breaking data into small chunks so that completely unnecessary pieces wont get loaded on unrelated page request. With scache_iov you can combine multiple path operations into single query.

As an another characteristic, all scache_iov operations (iops) will be completed before serving other clients, so scache_iov is atomic and suitable for situations where for example multiple values need to be stored without anyone else to get on middle.

While scache_iov is atomic, scache_iov is not transactional. Some of operations might fail and following are still executed independent from previous operations. Resulting drawback is that there is no usable scache_lasterr reporting for failed operations. Actually value of last error is undefined and caller have to analyze situation from iops' returned results.

Scache_iov expects valid connection resource and array of operations as arguments. On successful completion scache_iov returns array of results in same order and position as queried array of operations was. Operation is array containing iop-identifier, path and optionally value as third argument. These are defined in scache_iov's documentation.

$simplequery = 
  Array(Array(SCIOP_SET, 'my/path', 'my value'),
	Array(SCIOP_GET, 'my/path'),
	Array(SCIOP_UNSET, 'my'));

$conn = scache_reset('Example');
$result = scache_iov($conn, $simplequery);

/* returns $result as
Array
(
  [0] => 1            // SCIOP_SET succeeded, TRUE (1)
  [1] => my value     // SCIOP_GET returned 'my value'
  [2] => 1            // SCIOP_UNSET succeeded, TRUE (1)
)
*/

Note that scache_iov doesn't return FALSE (ie fail) if some of its packed operations fails. Scache_iov fails as function only if there is some severe problem like unexistent or expired session on network disconnection.

If some of operations fails, they just report their status on result array as like their single-op function equivalents would do.

$conn = scache_reset('Example');
$result = scache_iov($conn,
                     Array(Array(SCIOP_SET, 'my/path', 'my value'),
                           Array(SCIOP_ADD, 'my/path', 'new value'),
                           Array(SCIOP_GET, 'm/path')));
/* $result will be
Array
(
  [0] => true   // SCIOP_SET succeeded, TRUE (1)
  [1] => false  // SCIOP_ADD failed, add won't replace existing path
  [2] => false  // SCIOP_GET failed, typoed path does not exist
)
*/

Generally scache_iov is tool for bulk loading and bulk storing values on page scripts startup and finalization. Of course you can make use of list keyword for example by :

list($uid, 
     $login,
     $fname, 
     $sname,
     $someshareddata,
     $totalreqs) = scache_iov($conn,
                              Array(Array(SCIOP_GET, 'userdata/uid'),
                                    Array(SCIOP_GET, 'userdata/login'),
                                    Array(SCIOP_GET, 'userdata/fname'),
                                    Array(SCIOP_GET, 'userdata/sname'),
                                    Array(SCIOP_SHGET, 'shared/something),
                                    Array(SCIOP_VADD, 'shared/pagecount')));

Misc notes I

Lack of scache_lasterr reporting is not so bad that it sounds. Single-op example like :

if (!scache_add($conn, 'value', 'new-value')) {
    if (scache_lasterr($conn) == SCERR_EXISTS) {
       /* failed because did exist */
    }
}

can be written with iops like :

list($exists, $result) =
    scache_iov($conn, 
               Array(Array(SCIOP_STAT, 'value'),
                     Array(SCIOP_ADD, 'value', 'new-value')));
if (!$result && 
    ($exists = SCNODE_VALUE) || ($exists == SCNODE_BRANCH)) {
    /* failed because did exist */
}

We just test the existence before.

Iops are cheap and need not to be spared for performance reasons, vast majority of delays come from packet traversing on wire or kernels internal buffers. Scache_iov has artificial limit of max 127 ops for one call.

Misc notes II

Eventual and personally too common error message :

Fatal error: invalid operation: 0

results from invalid or mistyped SCIOP-identifier.

previous home next