Welcome to the world of SmartVariables
PLEASE READ THE 2 PDF DOCUMENTS in the "doc" sub-directory:
- DistributedProgramming.pdf (general SmartVariables concepts)
- GettingStarted.pdf (how to setup, and build systems)
In particular, the "GettingStarted" guide will aid you in setting this up.
SmartVariables is an advanced peer-to-peer, data sharing and GRID communications tool. This product will let you easily "glue" togeter systems that previously didn't share important data. Because the programmer API simulates intrinsic types and arrays of those, this product is simple to learn and use. It is also powerful.
SmartVariables objects can be named. The ability to name data and data collections allows others to express interest in content changes by "subscribing" to that data. New subscriptions reference data by their full name, which looks something like an email address. It is easy to name objects and lists.
Named objects persist themselves automatically, and intelligently. If an object's name contains an "@host" suffix, then it persists to the identified network machine automatically. Whenever a network-named object is modified, then that object's content changes are also propagated to all machines, processes and variables that previously expressed interest in the object. Interest is expressed by retrieving or changing object values, or by explicitly subscribing to an object. The data always "knows" who is using it. The data updates and propagates itself, as required.
SUPER-QUICK SMARTVARIABLES INSTALLATION INSTRUCTIONS
--------------------------------------------------------
Extract this distribution into your ${HOME} directory. Everything will extract under the folder "SmartVariables". The distribution contains both "debug" and "release" compiles of the SmartVariables libraries and server. This is a stable BETA release of our software. The "release" compile is faster and has a smaller memory footprint. The "debug" compile is easily debugged and method-traceable, however the "debug" code requires a lot of memory, so unless you need to debug problems, we recommed working with the "release" code.
CONFIGURATION SETUP
If you are using Apple or Linux, first edit the "env.sh" and customize your environment. Make sure the proper environment variables are set before starting the 'SVserver' modules or any SmartVariables application.
IMPORTANT - SmartVariables WILL NOT WORK IF IT CAN NOT LOCATE "smartvariables.conf"
Edit and install the "smartvariables.conf" configuration file. The configuration file must be where SmartVariables can find it.. it must exist in at least one of these 3 locations:
- "/etc/smartvariables.conf"
- "${HOME}/SmartVariables/smartvariables.conf"
- "C:\smartvariables.conf"
At a minimum, you must install and edit "smartvariables.conf" and set values for two entries: SMART_DIR and DB_DIR. If your Internet connection uses a proxy, then also set PROXYSERVER, PROXYUSERNAME and PROXYPASSWORD in the "smartvariables.conf" file. If you extracted this distribution into your ${HOME} directory (i.e. $HOME/SmartVariables) then the system will be able to find your smartvariables.conf run-time configuration. If a "global" configuration exists in "/etc" or "C:\" of your machine, then that one takes precidence. Once you have moved smartvariables.conf into a valid location, then edit that and firt change SMART_DIR to have your install directory, (for example "/Users/myhome/SmartVariables"). Also change DB_DIR to have the directory where your want your database to be created. If you don't use a web-proxy server, then leave the 3 PROXY configuration items set to empty (""); otherwise, set as needed.
DATABASE PLUGIN
This distribution contains a binary copy of Sleepycat Software's Berkeley DB database (version 4.3.27) for EVALUATION PURPOSES ONLY. Berkeley DB licensing information is on the web at http://www.sleepycat.com/download/licensinginfo.shtml Should you build any application that uses SmartVariables with Berkeley DB, you will need to be in compliance with BOTH the Berkeley DB licensing restrictions and the SmartVariables licensing restrictions before distributing your product. Please read Sleepycat Software's product licensing restrictions before installing. The Sleepycat Software web site for Berkeley DB is at http://www.sleepycat.com Also read SmartVariables product licensing restrictions at www.smartvariables.com SmartVariables internally uses the "libPlugDB" library for all database access. It is possible to extend libPlugDB to work with any vendor's database software. There is an open-source RAM plugin for systems with no hard drive for a database.
TRANSPORT PLUGIN
SmartVariables uses a default "Push" network transport module; however, alternate send/receive hooks have been provided via the Open Source "libPlugTRANSPORT" library. These allow any physical transport component to be used, including Sun's JXTA environment and BitTorrent. Note that JXTA is a "Pull" component. Both our default transport and the JXTA environment are capable of traversing firewalls transparently. The "libPlugTRANSPORT" interface can be extended for other transport mechanisms.
INSTALL PATHS
Windows users must manually add the installation library directory (where DLL's are) to their PATH variable: use control-panel->System->Advanced->Environment Varaibles. Add the new library directory, (for example: "C:\SmartVariables\release") to your PATH. Then you should reboot prior to using SmartVariables. Unix users must either add the install's library directory to their LD_LIBRARY_PATH or modify "/etc/ld.so.conf" to include the new SmartVariables library directory. In addition, Apple and Linux users might want to move their configuration file "smartvariables.conf" into "/etc". If you are behind a firewall and want to use SmartVariables across the that, then you need to install/run SmartVariables on the gateway machine and open port 9999.
STARTUP/SHUTDOWN
For windows users, use the 'SVserverGui' application to start, stop and pause the 'SVserver.exe' server sets. Unix users will either need to add startup for SVserver in "/etc/rc.d/rc.local" or else start the environment manually. When started from a command shell, pass the option '-d' to the SVserver to generate debug output on the standard output. Invoking 'SVserver.exe -q' will cause the environment to shutdown. Shutdown usually happens quickly. Invoking 'SVserver.exe -r' will try and rebuild and repair a corrupted database. To start the SmartVariables SVserver under Unix, use the command: "nohup $PATHTOEXECUTABLE/SVserver &" Note that three processes are started: a primary server, an "incoming" server, and an "outgoing" server (all named 'SVserver'). Should you wish to run the environment without network support, you can add the entry "NO_INTERNET_ACCESS 1" to "smartvariables.conf".
It may help to begin by using a shell window and invoking the SVserver program with debug enabled. That will let you see messages as they pass in and out of the system and to/from individual processes. We use the command "./SVserver -d | tee out" (or under Windows use Cygwin and tcsh to run "./SVserver.exe -d | tee out")
ABOUT WEB SERVICES
All SmartVariables objects can potentially function as web-service invokers. Once marked using the "MakeServiceInvoker()" method, an object can invoke a single dynamic method on a remote server when named and assigned. Service parameters are easily placed into the invoking object. Marked "service objects" only notify a single server, even if multiple service providers exist. The selected server is chosen at random. The name of a service results object should be passed as a parameter inside the invoking container or list.
EXAMPLE
We have supplied a simple example program to help you get started. Source is in the file "example/example.cpp". Be sure the SmartVariables "SVserver" programs are executing when running the example. As this sample-demo is "keyboard-input" driven, remember to press [enter] when you want to check the network for data. You also need to press [enter] to send data. This example is intended as a testing tool and tutorial only. The example is entirely text-based, and should be run from a command shell with a scrollable history.
A lot of work has gone into making the SmartVariables product for you.
enjoy.
FUNCTIONAL LIMITATIONS OF THE CURRENT BETA
--------------------------------------------
- Container objects may not directly contain the special ASCII characters:
0x00, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a
If it is necessary to place data that might contain some of these characters into a container object, then the container data must first be encoded by using the MemVar::EncodeBinaryData method. To decode encoded container data, use the method MemVar::DecodeBinaryData Additionally, programmers need to be careful using data which contains the special character '@'. SmartVariables uses the '@' character to delimit a hostname or Internet IP-address for objects.
- List objects may not contain elements that reside on different hosts. For example, it is not currently possible to have a single list object that contains an element ["foobar@host1.domain1"] and at the same time another element named ["foobar@host2.domain2"]. If it is necessary to manage list element objects that reside on different hosts, then an 'index' list must be used: A list can be created that contains only the names and locations of remote objects. When a specific object's contents are required, that object can be retrieved by using the name from the index list.
- All active container and list contents must be able to reside in the available primary memory. There is currently no provision to 'swap' unused list elements or containers to disk, other than that provided by the operating system itself.
- Only three 'SVserver' servers are currently started. Two of them handle incoming and outgoing data, and the third all local processing/routing. This is potentially a bottleneck for systems with many processors and affects network performance.
- Local processes are currently prohibited from writing to the database directly, and automatically pass write requests to the primary 'SVserver' for processing. This affects database performance.
- The current implementation of firewall code works for class "B" and "C"
networks. Set the configuration entry 'ALLOWCLASSBFIREWALL 1' for
class "B" networks.
Future versions of SmartVariables will remove these limitations.