Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A distributed lock server built on persistent socket connections, with an emphasis on preventing false positives

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 config
Octocat-spinner-32 lib
Octocat-spinner-32 .gitignore
Octocat-spinner-32 README
README
"What is pkLockServer?"

pkLockServer is a distributed lock server for PHP applications. pkLockServer is
intended to replace the use of flock() with a mechanism that is equally able
to detect clients that have died, yet also suitable for use where a filesystem
that supports flock() is not shared by all servers concerned.

"Why not use [x] instead?"

pkLockServer relies on persistent socket connections. The use of persistent
connections allows us to detect dead clients rather than using a timeout to
break locks as is commonly done with Redis, memcached, etc. We like to use
locks for mission-critical stuff and long-lived stuff. In both cases a 
false positive is infinitely worse than a false negative. So timeouts just
aren't a great choice for us. YMMV.

"How well does it work?"

pkLockServer is implemented as an efficient single-threaded server using 
select(). As such, the performance should be about as good as is possible in a 
pure PHP implementation. But in our case, we need locks in relatively few cases,
but when we need 'em we really need 'em to work. So performance is not the
biggest constraint.

"How do I test it? And how do I use it?"

pkLockServer's pkLockClient and pkLockServer classes have good phpdoc comments,
and they are demonstrated by the server.php and testClient.php programs in the 
bin/ folder.

Configure server.php by copying config/settings-example.php to config/settings.php
and reviewing the settings there. Then run the programs like this:

php server.php
[Leave that running; in another terminal window:]
php testClient.php

Fire up several copies of testClient.php to see how each holds the lock
for 10 seconds before yielding to the next waiting client, then lingers 
10 additional seconds before actually exiting. 

Note that, out of the box, server.php ignores connections that are not from 
127.0.0.1 (the same machine). You can edit your copy of settings.php to
limit connections to any suitable list of IP addresses. You want a limit to 
avoid DOS attacks. It's a pretty good idea to block the port at your firewall 
for outsiders too.

"What are those pkMessageServer and pkMessageClient classes about?"

These are pretty cool actually. pkMessageServer and pkMessageClient
implement message-based communication over TCP sockets, so you can conveniently
send and receive complete messages - anything that JSON can encode and
decode can be sent as a message. 

pkMessageServer looks for a 'command' key in the message. If the command
is 'lock', and a method called 'commandLock' exists, it is invoked
(much like writing actions in Symfony). 

These classes also support RPC (Remote Procedure Calls). 
pkMessageClient::rpc sends a message and waits for a response. Handy when
you need to know if you got that lock or not before proceeding.

There are phpdoc comments explaining how to leverage all this if you get
excited about writing your own subclasses to implement other applications
that call for persistent socket connections between PHP processes. It's
pretty neat what you can accomplish when you don't have HTTP tied
around your neck.

"How do I set this up as a Symfony plugin?"

Check it out via svn:externals to plugins/pkLockServerPlugin. The lib folder
will automatically be picked up by the Symfony autoloader.

"What are the license terms?"

Copyright 2012, P'unk Avenue LLC. Released under the MIT License.

"How stable is this?"

This is an early and exciting release! The test programs sure work though.
Put it through its paces for yourself and see. 
Something went wrong with that request. Please try again.