scache_rnpush
Description
scache_rnpush stores value as a last element to end of a ring in given path.
Though by definition ring has no ends - and neither has scached-rings - ring contains current position that can be changed with rotate function scache_rotf and scache_rnrotb. With scache_rnpush value is added as position preceding the current position. scache_rnunshift does opposite adding value to first element.
As like all other scached-functions, ring supports pathed keys. If existing multilevel path is overwritten on upper level, descending nodes are overwritten.
Parameters
Return values
TRUE on success, FALSE on fail. On FALSE scache_lasterr returns last error code which is one of below :
- SCERR_NO_SESSION Connected session does not exist or has been expired. Connection is not valid any more.
- SCERR_NO_ACCESS Ring operations is not allowed on assigned partition.
- SCERR_LIMITS_REACHED Partition has exceeded its memory or node limits and new session cannot be created until memory is freed.
- SCERR_NOT_CONNECTED Connection to backend is broken and cannot be reconnected.
- SCERR_PROTOCOL Internal protocol error has occurred when communicating to backend. This indicates something is severely broken.
Notes
Rings are generally useful for implementing FIFOs and LIFOs (queues and stacks). Most common user would be web clients feeding data to work-queues to be consumed by separate dedicated external server process.
In work-queue setups, special considerations need to be taken to ensure there is always some consumer to consume queue-pushed data. As a safety measure, ring has size limits. After exceeding limits, additions will fail with SCERR_LIMITS_REACHED.
Due to nature of ring-type implementation there is no performance penalties on operating on either end of ring.
Example
<?php $conn = scache_reset(md5(uniqid())); /* purge possible pre-existing. rings are shared and persistent */ scache_rnclear($conn, 'queue'); /* FIFO (Queue) */ scache_rnpush($conn, 'queue', 1); // return true scache_rnpush($conn, 'queue', 2); // return true scache_rnpush($conn, 'queue', 3); // return true echo scache_rnshift($conn, 'queue') . "\n"; // displays 1 echo scache_rnshift($conn, 'queue') . "\n"; // displays 2 echo scache_rnshift($conn, 'queue') . "\n"; // displays 3 /* LIFO (Stack) */ scache_rnpush($conn, 'queue', 1); // return true scache_rnpush($conn, 'queue', 2); // return true scache_rnpush($conn, 'queue', 3); // return true echo scache_rnpop($conn, 'queue') . "\n"; // displays 3 echo scache_rnpop($conn, 'queue') . "\n"; // displays 2 echo scache_rnpop($conn, 'queue') . "\n"; // displays 1 ?>