#@ #@ Dklab Realplexor: Comet server which handles 1000000+ parallel browser connections #@ Author: Dmitry Koterov, dkLab (C) #@ GitHub: http://github.com/DmitryKoterov/ #@ Homepage: http://dklab.ru/lib/dklab_realplexor/ #@

BUILD A BINARY FROM C++ SOURCES

Realplexor comes in two versions with exactly same functions and even exactly same (shared) smoke tests code:

1. Perl version: treated as a prototype and development/debugging playground. It's quite slow and is not recommended in production.
2. C++ version: fast, but you should build it by yourself from sources (it's quite easy in Ubuntu 12.04), see cpp/ directory.

When you build a binary version of Realplexor, the binary is put to the current directory; it will be used instead of Perl version automatically.

INSTALLATION ON LINUX

Note that Realplexor works on Linux only, other OS (Windows, MacOS, FreeBSD) are not known to be supported.

0. Build a binary file ./dklab_realplexor from C++ source code if you can (see cpp/ directory for instructions).

1. If you decide to use a Perl version, run ./dklab_realplexor.pl manually and check that all needed libraries are installed. If not, install them:

   • For RHEL (RedHat, CentOS):

     yum install gcc

     perl -MCPAN -e "install EV"

   • For Debian (or Ubuntu):

     apt-get install gcc

     perl -MCPAN -e "install EV"

2. Copy Realplexor to /opt/dklab_realplexor (or you may create a symlink).

   cp -a . /opt/dklab_realplexor

   • or -

   ln -s pwd /opt/dklab_realplexor

3. Create /etc/dklab_realplexor.conf if you need a custom configuration. (You may create a symlink instead of creating the file.)

   cat > /etc/dklab_realplexor.conf

   $CONFIG{WAIT_ADDR} = [ '1.2.3.4:80' ]; # your IP address and port $CONFIG{IN_ADDR} = [ '5.6.7.8:10010' ]; # for IN line return 1; ^D

   • or -

   ln -s /path/to/your/config.conf /etc/dklab_realplexor.conf

4. Use bundled init-script to start Realplexor as a Linux service:

   ln -s /opt/dklab_realplexor/dklab_realplexor.init /etc/init.d/dklab_realplexor

5. Tell your system to start Realplexor at boot:

   • For RHEL (RedHat, CentOS):

     chkconfig --add dklab_realplexor

     chkconfig dklab_realplexor on

   • For Debian (or Ubuntu):

     update-rc.d dklab_realplexor defaults

     update-rc.d dklab_realplexor start

SYNOPSIS

1. In JavaScript code, execute:

var realplexor = new Dklab_Realplexor("http://rpl.yoursite.com/"); realplexor.subscribe("alpha", function(data) { alert("alpha: " + data) }); realplexor.subscribe("beta", function(data) { alert("beta: " + data) }); realplexor.execute();

2. In PHP code, execute: require dirname(FILE) . '/Dklab/Realplexor.php'; $realplexor = new Dklab_Realplexor("127.0.0.1", "10010"); $realplexor->send(array("alpha", "beta"), "hello!");

3. See more details in Realplexor documentation.

LOG MNEMONICS

pairs_by_fhs Number of active TCP connections on WAIT line (clients).

data_to_send Number of IDs with non-empty command queue.

connected_fhs Number of IDs which are listened by at least one client.

online_timers Number of "online" client identifiers. Client is treated as online if:

• it has an active connection;
• or it does not have a connection, but disconnected no more than OFFLINE_TIMEOUT seconds ago.

cleanup_timers Number of IDs which queue must be cleaned if no activity is present for a long time. This is a unused IDs garbage collector statistics.

events How many events (e.g. ONLINE/OFFLINE status changes) are collected by realplexor. Event queue is limited by size.

CHANGELOG

• Dklab Realplexor 2014-01-14: v1.41

  • [MIN] Brushed up C++ version, Ubuntu 12.04 build instructions.
  • [MIN] Banner comments added to source files.
  • [MIN] Tabs to spaces.
  • [BUG] GCC 4.7 compatibility & GCC bug work-around

• Dklab Realplexor 2011-07-28: v1.40

  • [NEW] Python API added (experimental)
  • [NEW] Added missed "return this" for chained JS calls.
  • [BUG] Firefox 4 bugfix against 'attempt to run compile-and-go script on a cleared scope'.
  • [BUG] Minor changes & better support for phpt tests.
  • [BUG] No OFFLINE event should be generated until the last connection with ID is disconnected.
  • [BUG] If no IDs are subscribed in JS, do not connect to the server with empty ID list.

• Dklab Realplexor 2010-08-11: v1.32

  • [SPD] When empty HTTP body is passed to IN connection, it is now ignored, no warnings generated.
  • [SPD] Remove old data from channels BEFORE data processing/sending.
  • [BUG] Use print instead of syswrite, because for large amount of data syswrite sometimes returns before all this data is transmitted.

• Dklab Realplexor 2010-04-16: v1.31

  • [BUG] Perl does not call flush() automatically before socket shutdown(). It sometimes (unstable!) causes unexpected SIGPIPEs and data loss. Fixed: now flush() is called manually.
  • [BUG] STATS command is not processed twice anymore.
  • [NEW] Ability to limit memory usage and auto-restart the daemon if it consumes too much memory. (Note that unsent data is lost during this restart.)
  • [NEW] PHP API: cmdOnlineWithCounters(): for each online ID also returns the number of browsers connected just now (it is NOT a "number of online users who listen this channel", but its approximation).
  • [BUG] Minor fixes in clean_old_data_for_id (bug is not reproduced, but now surrounding code is better).
  • [NEW] Visibility:hidden for IFRAME. It is good when BODY has relative position.
  • [BUG] Allow to pass a scalar to 2nd parameter of cmdWatch($fromPos, $idPrefixes).

• Dklab Realplexor 2010-02-27: v1.30

  • [SPD] Use EV library (http://search.cpan.org/~mlehmann/EV-3.9/EV.pm) instead of libevent. It is faster and has no memory leaks.

• Dklab Realplexor 2010-01-30: v1.24

  • [BUG] Avoid warnings in log on unexpected disconnect.
  • [NEW] Refactoring and profiler support.
  • [SPD] Do not create extra shell while calling ulimit.
  • [NEW] Support for per-config log facility.
  • [SPD] Profiler tool with IN line ignorance. Avoid BigFloat in events: 45% speedup. Apache ab patched utility.
  • [SPD] Keep channels pre-sorted after addition. It speedups 60%, because we need less cursor comparisions.
  • [SPD] STDOUT buffering in non-verbose mode. More verbosity levels. Logger speedup. Custom config for profiler script.

• Dklab Realplexor 2009-12-26: v1.23

  • [BUG] Empty identifier passed to IN line ("identifier=") caused warnings.
  • [SPD] Lower the number of useless debug lines and connection's name() calls.
  • [BUG] Improved init script: more time to restart and better signal handling.

• Dklab Realplexor 2009-12-24: v1.22

  • [BUG] SIGPIPE causes the script to restart on some unexpected client's disconnects.

• Dklab Realplexor 2009-12-22: v1.21

  • [NEW] ID queue is cleaned after CLEAN_ID_AFTER seconds when no data arrived (previously OFFLINE_TIMEOUT was used for that).
  • [NEW] To unsubscribe all callbacks from a channel: rpl.unsubscribe("channel", null).

• Dklab Realplexor 2009-12-16: v1.15

  • [NEW] When IDs list is long, JS API uses POST request instead of GET.
  • [NEW] IN line now fully supports HTTP POST.
  • [NEW] Non-200 responses from IN line are converted to exceptions.
  • [NEW] Content-Length verification in PHP API.
  • [NEW] Support for SSL in IN line for PHP API (use 443 port).
  • [BUG] If callback called execute(), extra request was performed.
  • [BUG] Referrer header was not ignored by server engine (bad if it contains IFRAME marker).