[BTC-dev] (EXPERIMENTAL) Introducing: Shiva.

[Stanislav Datskovskiy]

Name: README.txt
URL: <http://therealbitcoin.org/ml/btc-dev/attachments/20160128/README-0001.txt?sha1=c0dcef9fda89a30aa128a0c9ae0bd32320cfcef4>
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

 /****************************\
*        EXTREME DANGER:       *
* AFFECTS MULTIPLE SUBSYSTEMS! *
*    CONTAINS TCP LISTENER!    *
*    FOR LABORATORY USE ONLY.  *
********************************
          ************
         **************
        ****************
       ****   ****   ****
       ***     ***    ***
       ***     ***    ***
        ***    * *    **
        ******** ********
        *******   ******
            ***   **
          *  ******* **
          ** * * * * *
    **     *         *     ***
   ****    * *     * *    ****
   ****    *** * * **     ***
    ****    *********   ******
   *******    *****    *******
   *********        ****** **
    **   ******   ******
           **  *******       **
   **       *******         ***
  ****   ********  ************
  ************    ************
   ********             *******
  ******                   ****
   ***                      ***
********************************

Shiva is a Lisp shell for TRB.

Presently we are using the very well-known TinyScheme.
See the new subdirectory 'shiva'.

Shiva is split into TWO patches, for readability.

asciilifeform_shiva_part_1_of_2.vpatch .... ONLY the shiva (tinyscheme) subdir.
asciilifeform_shiva_part_2_of_2.vpatch .... Everything else.

How to use
~~~~~~~~~~

./bitcoind -shiva -shivainit=./shiva/init.scm  ....SNIPSNIPSNIP...

if you want a custom port, -shivaport=31337 or whatnot.

Shiva will start up ONLY AFTER the node is 'warm' (i.e. has snarfed up the db.)

The following session demonstrates the two example Shiva hooks currently implemented,

These look like this:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(shiva.cpp)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* Get current best blockheight. */
static pointer btc_get_best_height(scheme *sc, pointer args) {
  return sc->vptr->mk_integer(sc, nBestHeight);
}


/* Initite a shutdown. */
static pointer btc_shutdown(scheme *sc, pointer args) {
  CreateThread(Shutdown, NULL);
  return sc->NIL;
}


/* Install the hooks. For each of the above, must do this: */
static void init_shiva_hooks(scheme *sc) {
  scheme_define(sc, sc->global_env, mk_symbol(sc, "btc-get-best-height" ), mk_foreign_func(sc, btc_get_best_height));
  scheme_define(sc, sc->global_env, mk_symbol(sc, "btc-shutdown" ), mk_foreign_func(sc, btc_shutdown));
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


~ Now, let's try actually using them: ~


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ telnet 127.0.0.1 1336
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
Shiva: using init file ./shiva/init.scm

#>(btc-get-best-height)
395542
#>(btc-shutdown)
()
#>(quit)
Connection closed by foreign host.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Not earth-shakingly useful, but illustrates how to implement these.
Eventually we can migrate the whole RPC orchestra to this.


Other notes:
~~~~~~~~~~~~

* If Shiva is disabled, it spawns no threads, does not listen on any port, etc.
* You can have multiple independent Shiva instances.
* You MUST set an init file if Shiva is enabled.
* Shiva listens INADDR_LOOPBACK, you must connect from localhost.
* Presently the node will only shut down once the last Shiva is down.
* A Shiva session currently terminates when the connection is dropped.
* Presently, Shiva does not persist lisp world across sessions.
* Study the TinyScheme source to understand how these are to be implemented.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)

iQEcBAEBCgAGBQJWqth5AAoJELmCKKABq//HuUsH/j4p09TfHg3o6reI/AJ/+lfz
TNCOq1aOM0Oy+2ZO3U2UtKB9Je32zWJBdUx778uxlSJ1XYTNsUKu35ijQX+WmxsS
fWXxwNQ/6dfub1+X5J7HRV2nax6RyQnprdIRZxLQO+8uQHl7nb64/5CSkxqhi3f0
UVRPdM1uE4KlCKxbIKPo+BKz2T0OREu2Rz2X7AHI2SHIBNxObYXbheDjRpQsuMkc
/o25FCxUUrwluTRnbH9BtbVnjFdnXUjpuJnw4gDehp1XqLAHbiPdzl3knGN/L/zW
Sl+4iGIUtemA8ZsuYhF69wJBeTuhoa+io98URZe/nyfPsQQszC4/4bZl1zsMCYM=
=ZVPv
-----END PGP SIGNATURE-----
-------------- next part --------------
A non-text attachment was scrubbed...
Name: asciilifeform_shiva_part_1_of_2.vpatch
Type: application/octet-stream
Size: 261819 bytes
Desc: not available
URL: <http://therealbitcoin.org/ml/btc-dev/attachments/20160128/asciilifeform_shiva_part_1_of_2.vpatch?sha1=8d22942ffc97296845fad81c3a78acfdf54af23a>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: asciilifeform_shiva_part_1_of_2.vpatch.asciilifeform.sig
Type: application/octet-stream
Size: 490 bytes
Desc: not available
URL: <http://therealbitcoin.org/ml/btc-dev/attachments/20160128/asciilifeform_shiva_part_1_of_2.vpatch.asciilifeform.sig?sha1=fb387f325d6a91f1da3f00b77acd965563c3c019>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: asciilifeform_shiva_part_2_of_2.vpatch
Type: application/octet-stream
Size: 13644 bytes
Desc: not available
URL: <http://therealbitcoin.org/ml/btc-dev/attachments/20160128/asciilifeform_shiva_part_2_of_2.vpatch?sha1=abc9c21e3c86e7a540b20e49a6ebc86017758e48>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: asciilifeform_shiva_part_2_of_2.vpatch.asciilifeform.sig
Type: application/octet-stream
Size: 490 bytes
Desc: not available
URL: <http://therealbitcoin.org/ml/btc-dev/attachments/20160128/asciilifeform_shiva_part_2_of_2.vpatch.asciilifeform.sig?sha1=b1f26fb0b31902d3fee7a2709340a1ecb2d421f8>