_______                          .__ .__   .__   .__                 
      \      \    ____   __ __ _______ |__||  |  |  |  |__|  ____    ____  
      /   |   \ _/ __ \ |  |  \\_  __ \|  ||  |  |  |  |  | /  _ \  /    \ 
     /    |    \\  ___/ |  |  / |  | \/|  ||  |__|  |__|  |(  <_> )|   |  \
     \____|__  / \___  >|____/  |__|   |__||____/|____/|__| \____/ |___|  /
    =========\/======\/=================================================\/==
  v0.01 04/JUL/2007 (C) Copyright 2007-2007 Scott D. Yelich SOME RIGHTS RESERVED
 .,-*~'`^`'~*-,._.,-*~'`^`'~*-,._.,-*~'`^`'~*-,._.-*~'`^`'~*-,._.,-*~'`^`'~*-,. 



This is the "README" for the Neurillion free web page counter multi v2 
http://www.neurillion.com/p/33/counters/multi/v2/README

The software is released under Creative Commons - Attribution 3.0 unported 
see: http://creativecommons.org/licenses/by/3.0/legalcode

See "LICENSE" for text, URL above for latest version.

See "INSTALL" for information on installation (and usage).

See "TODO" for ideas about what could be done in a next version.


WARNING:  Any file that can be opened for reading may be accessed via the
          image path feature of this counter.


The idea with this counter is the desire to use images for the digits
of the counter.  At the same time, the initial version of the counter
was meant to be quick to implement and not have any dependencies
(other than the digit images) -- so a program such as ImageMagick's
montage isn't used to create a single image vs the individual calls
now.  So, an advantage of the individual calls is that each image
could be in a separate location on the web page -- but a disadvantage
is that it takes multiple calls to the server.  For 12 digits in a
counter, it would require 12 calls to the server.

Another issue with multi is how to register the "hits" -- as each call
to the server for a 12 digit counter couldn't register a hit -- or the
hits would go up by 12!  This was solved by using the digit position
specification as a flag -- so only the call to get the digit in
position one actually increases the hit... of course, if you only call
for digits position 2 through 12, for example, the counter would never
be incremented!

And if that wasn't enough to worry about -- it gets even more
complicated:

The quirk is that due to the multiple calls to the server to read the
count value, this value can't change in the middle of mutiple calls to
read the digits of a specific total.  As an example, if the count is
89 and there are two page loads (ie hits) in progress, there could be
a potential for an incorrect digit to come back as the first hit count
should be 89 and the second should be 90 -- but if the count is
updated due to the second hit while the first page is still getting
the digits -- and the first page load experiences a delay in the call
to the server, intead of a 9 the last digit would be 0 and the counter
would be displaying 80 instead of 89 (or the exactly accurate 90).
Since there's no way to undo the 8 that was previously sent, the best
that can be done is to try to keep the count at 89 so the 9 is
returned, even thoguh there was a delay.  A non-foolproof but simple
mechanism is used to combat this.  This counter has a write total and
a read total.  The behaviour is that when the write total is updated,
if the last time this total was updated is greater than a configurable
setting number of seconds earlier (ie: default is 2 seconds) -- then
the new write total will also be written to the "read" total.  In all
cases, all of the digits are returned from the value of the read
total.  The idea here is that the update delay is longer than the time
it takes to make all the calls to the server to read all of the digits
(but, of course, this isn't foolproof, but should be "good enough").
Increasing the delay should lead to fewer incorrect counts being
display, but also in a more "jumpy" counter if the page gets a lot of
hits quickly.

v2 of this counter *does* account for concurrency.


Enjoy!

Scott