Release notes
Version 1.1.4
Additional changes to add php8 required arginfo.
Version 1.1.3
Minor change on debian package build rules to allow building for php8. No changes on code.
Version 1.1.2
Minor change on debian package build rules to allow building for php7.4. No changes on code.
Version 1.1.1
Minor change on debian package build rules to allow building for php7.3. No changes on code.
Version 1.1.0
PHP extension ported to support PHP7.x -series. Support for PHP4 -series dropped (thought it probably still compiles and works)
Version 1.0.0
New IOPs SCIOP_MOVE and SCIOP_SHMOVE for moving stored data as complete tree from one point to another. New functions :
- scache_move for private keyspace.
- scache_shmove for shared keyspace
Move -operations helps with complex data structures, that cannot be constructed with single scache_iov -operation. With move you to construct data-containing hierarchy on temporary location and when complete, move it as a whole to shared well known location replacing possible previous structure atomically.
Added new configuration option create-on-first-use that instructs backend to initialize nonexisting sessions on their first use. With this option enabled you can scache_connect to new session identifier and directly operate on it. With this option disabled, backend reports SCERR_NO_SESSION until you first either scache_open or scache_reset it.
create-on-first-use defaults to false to preserve previous behaviours of previous releases.
As usual, this release changes wire protocol again breaking backward binary compability with previous versions. Both scached and all connecting php-extensions must be upgraded and php accelerators' (eaccelerator, apc, xcache) caches must be purged.
Version 0.99.3.1
Besides being fundamentally broken, scache_add and scache_shadd operations had crash bug that killed backend when trying to overwrite previously existing upper path. This is fixed in version 0.99.3.1
The fix affects backend daemon (scached), that needs to be updated and restarted. The php extension is not modified and update is not required.
Version 0.99.3
New IOP SCIOP_LASTERR added to scache_iov to retrive error codes inside from bulk queries. Also initially broken IPv6 connectivity on extension is finally fixed.
Besides of these, this release contains no other bugfixes. If you are already happy without SCIOP_LASTERR and IPv6 addressing, there is no need to upgrade.
But if you decide to upgrade, protocol has changed again breaking backward compatibility with previous versions. Both scached and all connecting php-extensions must be upgraded and php accelerators' (eaccelerator, apc, xcache) caches must be purged.
Version 0.99.2.1
Minor fix to get extension compile on PHP 5.4. No reason to upgrade from previous version.
Version 0.99.2
This version adds new IOP to scache_iov -call for detecting race conditions on multi client updates to same content. In short SCIOP_VBRK compares counter on given path and skips all following writing IOPs, if value does not equal the value given as parameter.
Other changes
- Documentation updates
- Alias SCIOP_CLEAR for SCIOP_UNSET
- Alias SCIOP_SHCLEAR for SCIOP_SHUNSET
- Alias SCIOP_VCLEAR for SCIOP_VUNSET
This release contains no bugfixes, so if you are already happy without SCIOP_VBRK, there is no need to upgrade.
As usual, protocol has changed again breaking backward compatibility with previous versions. Both scached and php-extension must be upgraded and php accelerators' (eaccelerator, apc, xcache) caches must be purged.
Some notes
What is scache's current status? There has been some guestions about scache being beta or pre-beta or something else :
Thought its version number is below 1.0, I personally regard is as "stable enough" (currently 0.99.1 being stablest around). It is used on production environments and there has not been crash bugs since version 0.90.7. Scache will be 1.0 when there is quite nothing to add or quite nothing to do differently, but there might still be long road for that kind of perfection.
In this case the "stable enough" means that it don't crash and it does what it's expected to do, but it might have some gotchas, and it might be possible to deliberately crash it for example by dumping enough garbage to it.
Currently biggest problem is in documentation. For 90% of time, scached does what documentation says. For 9% of time it does the right thing, but documentation claims it wrong. And for last 1%, documentation says it right, but scached does it wrong. Current documentation lacks code examples that would explain philosophy and good practices to sum up newbie tutorial for new converts. I'm smoothly forced to accept the fact, that there won't be popping out any blogging volunteers to write them up and I need to do it myself.
Scached is designed to be cheap tool to overcome those race conditions surrounding multi-client operations on shared data, but current documentation does not open the case.
Another problem is upgrade. Being memory backed only, upgrading that requires restarting the backend, that unfortunately kills all session it contains. There is ways to overcome that, for example gradually transfering sessions by assinging new sessions to parallel upgraded scached by prefixing and detecting prefixed session identifiers. Anyway, scached won't ever be disk backed, but there might eventually be slight urge to dump snapshot to disk on exit for restarted scached on prepopulate itself from.
Third requirement for 1.0 is testing in various different scale environments. One lesson learned is, that people tend to use things very differently from how you planned them to be used. So there is need for even more users and feedback. Please keep sending success reports, failures, things that bother and questions to scache@nanona.fi
Version 0.99.1
New features
Accumulator code is enabled. Accumulator allows referring previous values in IOP bulk requests. Usage is documented under scache_iov.
Other changes
To blow up protocol once again, key- and value length are widened to full 32 bit integers instead of packing them both to one 32 bit value field like old versions did. This protocol modification allows larger keys and values thought currently clipped in ext/php-scache-proto.h to 16384 bytes for key and 524288 bytes for value.
As we have already been familiar to, this new release is again protocol incompatible to previous releases and both scached and php extension must be upgraded.
Version 0.99.0
API changes
- Added ring datatype to backend for implementing queues and stack. New api contains functions :
- scache_rnpush and scache_rnunshift for data queueing
- scache_rnpop and scache_rnshift for data purging
- scache_rnrotf and scache_rnrotb for ring rotation
- scache_rnget for data polling
- scache_rnsize and scache_rnclear for remaining ring operations.
- Return values of clearing functions scache_clear, scache_shclear, scache_chclear and scache_rnclear is changed.
- Using shared dataspaces require from now on valid initialized session.
Previously these functions returned TRUE if something got cleared and FALSE with error code SCERR_NOTEXIST if given path did not exist. More practical approach is to return TRUE also for SCERR_NOTEXIST, so that returned value TRUE singals empty node whether being cleared or already initially empty.
However error code SCERR_NOTEXIST is still set, so combination of return value TRUE with error code SCERR_NOTEXIST is possible and can be used detect more exact result status.
This does not apply scache_vunset. scache_vunset returns FALSE if path does not exist.
Good news is that this harsh backward compability breaking policy change doesn't actually break backward compability. Previous versions contained bug in scached that did forbid usage of shared namespaces without valid initialized session althought documentation expressed it as legal operation.
Policy change has been done for performance reasons. Without bound session, connecting clients partition need to be expensively resolved up for every request.
If you are not using private sessions, you can always connect to static dummy fake session.
Bug fixes
- Fixed unmaintained session handler emulation. Session handler warned when storing empty $_SESSION. Thanks for reporting.
Other changes
- Maximum length of key is reduced to 8189 bytes to allow maximum size of value increased to 524270 bytes. Previous impractical split was 16bits for key, 16bits for payload, new split is 13bit/19bits.
- As a result, scached-protocol is blown up once again and not compatible between previous version. BOTH SCACHED AND PHP-EXTENSION MUST BE UPGRADED.
Known issues
- Generally scache_lasterr() is undefined if operation succeeds. Most functions set last error status as SCERR_SUCCESS, but not all.
Future plans
- scache_iov contains accumulator code to allow referencing previously accessed value. With accumulator data can be atomically transfered between namespaces.
- Besides pending standalone emulation script, no other functionality won't probably be added. After enough testing and success reports, current set will be eventually declared as version 1.0
Version 0.90.7
API changes
- Added class interface SCache for those who prefer more object-oriented way of life.
- Added aliases scache_clear, scache_shclear, scache_vclear for scache_unset, scache_shunset, scache_vunset to keep symmetry with class interface. Word unset is PHP reserved word and not allowed as class method.
Bug fixes
- Partial fixes for buggy documentation
- Added delay to init scripts to prevent failure on restart
Other changes
- Hardcoded unix socket path /var/run/scached.sock has been removed. New default path is relative to installation directory.
- Build process is changed to build both daemon and extension in one run instead of requiring separate phpize, configure and build for extension.
Future plans
- "Accumulator", special (null) value indicating last operation result to make atomic moves and copies possible with scache_iov
- Plain PHP-written emulation script that can be included for standalone and testing purposes.
- FIFO/LIFO queues, if any kind of usage scenario for them can be figured out
- Win32 compilable extension.
- Version bumping to 0.99.0 to be start stabilization to 1.0.0
Version 0.90.6
Important!
- Protocol has changed again, so neither daemon or extension are backward compatible and both must be upgraded.
- Both daemon and extension still use hardcoded unix socket path /var/run/scached.sock, so keep on bewaring of not overwriting production versions socket when testing new versions on production platform.
API changes
- Added functions scache_coll and scache_shcoll for listing contents of path.
- Added iop SCIOP_COLL and SCIOP_SHCOLL for doing same through scache_iov interface
Bug fixes
- If compiled with asserts enabled (--enable-devel), server asserted when empty path (/) was queried. Does not affect prepackaged or production versions.
Version 0.90.5
API changes
- Added session renaming capability and api function scache_rename.
- Both scache_stat and scache_shstat are changed to report nodetype SCNODE_EMPTY separately now. Previously empty nodes were reported as SCNODE_NONEXISTING.
- scache_unset, scache_shunset, scache_vunset and scache_chclear return FALSE with error code SCERR_NOTEXIST if path specified did not exist. Previously reported value was TRUE to express path not existing, not the actual result of operation itself.
- scache_status returns TRUE or FALSE depending whether specified session is valid. Previously status query succeeded always as long as connection was valid.
- Error code SCERR_INVALID_CALL is merged to error SCERR_PROTOCOL
Bug fixes
- scache_drop is fixed to destroy session immediately instead for marking it expirable. This caused error when trying to reuse same session id immediately.
- Fixed scache_getopt and scache_setopt to report errors correctly. Previously on failures execution was terminated with zend_error.
- Changed non-persistent connection attempt to not use already available connections to same hosts. Previously cached connections were always used even if non-persistent connection was requested.
Other changes
- All error reporting is revised, unified and documentation updated to reflect actual operation instead of planned operation.
- Added short tutorial
- Both daemon and extension are changed to use hardcoded unix socket path /var/run/scached.sock until better solution is done. Beware of not overwriting production versions socket when testing new versions on production platform.
Late additions, IMPORTANT!!
Protocol has changed between 0.90.4 and 0.90.5. This means that 0.90.5 scached and extension are incompatible with previous versions and you need to update both ends.
Especially if you are using some php accelerator like APC or eAccelerator, you might need to purge cached scripts to get them forcibly refreshed to changed SCIOP-numbering. For example with eAccelerator, when cached scripts are stored onto filesystem also, they survive even apache's restart and won't be automatically refreshed until their original source files change.
Either purge your opcode cache or touch every script file to get it reloaded. Otherwise scripts picked from cache use wrong SCIOP-numbers and fail like:
invalid operation: 4