Changeset 8146 in project


Ignore:
Timestamp:
02/04/08 20:26:40 (12 years ago)
Author:
rm
Message:

Changes applied for rm (97.76.48.98) through svnwiki:

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/flux

    r7979 r8146  
    1 [[tags: egg]]
    2 
    3 == flux
    4 
    5 [[toc:]]
    6 
    7 === Introduction
    8 
    9 Flux (Fast Light Unified eXchange) is a new paradigm in distributed computing.
    10 Flux uses the concept of nodes or "agents" to create a distrbuted environment.
    11 Agents do not have any previous knowledge of how to perform tasks unless first
    12 instructed.  Asychronous reponse data can be retrieved by also supplying the
    13 remote node the code with which to respond.  This paradigm is meant to keep
    14 control over source code in the hands of the developer.  Flux can be used
    15 as an RPC system as well, the largest difference here is that in traditional
    16 RPC systems the remote end already knows how to perform an action and has
    17 an interface exposed.  In Flux we provide the interface to the remote node.
    18 Flux also has a simple directory mechanism so that nodes can find each
    19 other.  Requests can be direct or indirect, either to a single node by name
    20 or to all nodes by setting the node name to #:all using the directory.
    21 
    22 === Authors
    23 
    24 [[Raymond Medeiros]]
    25 
    26 [[elf]]
    27 
    28 === License (BSD)
    29 <blockquote>
    30 Copyright (c) 2008, Raymond Medeiros
    31 All rights reserved.
    32 
    33 Redistribution and use in source and binary forms, with or without
    34 modification, are permitted provided that the following conditions are met:
    35     * Redistributions of source code must retain the above copyright
    36       notice, this list of conditions and the following disclaimer.
    37     * Redistributions in binary form must reproduce the above copyright
    38       notice, this list of conditions and the following disclaimer in the
    39       documentation and/or other materials provided with the distribution.
    40     * Neither the name of Rooted Logic LLC, the author nor the
    41       names of its contributors may be used to endorse or promote products
    42       derived from this software without specific prior written permission.
    43 
    44 THIS SOFTWARE IS PROVIDED BY Raymond Medeiros ``AS IS'' AND ANY
    45 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    46 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    47 DISCLAIMED. IN NO EVENT SHALL Raymond Medeiros BE LIABLE FOR ANY
    48 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
    49 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    50 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    51 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    52 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    53 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    54 </blockquote>
    55 === Requirements
    56 
    57 Requires {{posix}}, {{tcp}}, {{srfi-1}} {{srfi-18}} and {{args}} at compile-time
    58 
    59 === Documentation
    60 
    61 What follows is a description of the {{flux}} extension library.
    62 
    63 ==== flux
    64 
    65 ===== Usage
    66 
    67 {{(require-extension flux)}}
    68 
    69 ===== start-node
    70 
    71  [procedure] (start-node "node-name" node-ip-address node-port directory-ip-address directory-port local-repl)
    72 
    73     This procedure starts a node, you must supply a string for node-name, ip-address of the local machine,
    74     a port number, as well as the directory ip-address and port number (this can be the local node as well).
    75     The last option local-repl takes a boolean and determines whether a local repl "console" should be
    76     started for this node, #:none will cause the node to not join the current thread. 
    77     You can also run multiple "nodes" within a single process for testing purposes.
    78 
    79 ===== send-to
    80 
    81  [procedure] (send-to remote-node `(CODE))
    82 
    83     This procedure will allow you to send code to a specific remote node or all nodes if remote-node is replaced
    84     with #:all.  Code must be pre-fixed with unquote.  Please see the examples below for more details.
    85 
    86 ===== delete-self
    87  
    88  [procedure] (delete-self directory-ip-address directory-port node-ip-address node-port)
    89 
    90     This procedure should be called as part of your shutdown routine (this is handled in flux-capacitor by a UNIX signal handler).
    91     It's purpose is to remove the node cleanly from the directory.
    92 
    93 === Examples
    94 
    95 ==== Library Example
    96 
    97 <enscript highlight=scheme>
    98     ; Start a directory node with local-repl, register with ourself   
    99     (start-node "directory" "127.0.0.1" dir-port "127.0.0.1" dir-port #t)
    100 </enscript>
    101 
    102 <enscript highlight=scheme>
    103     ; Start an agent node "agentA" on another port, with a local-repl, register with the directory node
    104     (start-node "agentA" "127.0.0.1" 10001 "127.0.0.1" dir-port #t)
    105 </enscript>
    106 
    107 <enscript highlight=scheme>
    108 ; create a static local callback for retrieving result sets
    109 (define my-callback
    110   (lambda (a b)
    111    (printf "a: ~A, b: ~A ~%" a b)))
    112 
    113 ; describe remote code to all nodes (including directory node)
    114 
    115 ; lexically local
    116     ; define a set of lambda's using let, tell the remote node to respond using send-to and send the result of x & y to local-node
    117     ; please note that the quoting and unquoting is necessary to determine which code is executed locally and remotely
    118     (send-to #:all `(let ((x (lambda (x) (add1 x))) (y (lambda (x) (add1 x)))) (send-to ',(local-node) `(my-callback ,(x 1) ,(y 1)))))
    119 
    120 ; using global define
    121     ; first define (plus1) on the remote nodes
    122     (send-to #:all `(define plus1 (lambda (x) (add1 x))))
    123     ; tell the remote nodes to call (plus1) and then make a call to (my-callback) with the results
    124     (send-to #:all `(send-to ',(local-node) `(my-callback ,(plus1 1) ,(plus1 1))))
    125 </enscript>
    126 
    127 ==== Command Line Interface Example
    128 
    129 Flux also comes with a simple command line interface wrapper
    130 
    131 <enscript highlight=bash>
    132 
    133 $ flux-capacitor
    134 
    135 Usage: flux-capacitor (options)
    136  -h, --help               Display this text
    137  -c, --console            Enter interactive mode
    138  -n, --name=NAME          Name for this node
    139  -d, --directory=IP:PORT  Directory ip:port combination
    140  -l, --local=IP:PORT      Local ip:port combination
    141  -f, --file=FILE          execute a script
    142 
    143 start a local directory node
    144 
    145 $ flux-capacitor -d 127.0.0.1:10000 -l 127.0.0.1:10000 -n directory -c
    146 #;> (get-peers)
    147 ((directory 127.0.0.1 10000) (agentA 127.0.0.1 10001))
    148 #;>
    149 
    150 start a local agent node, and send a request to the directory node
    151 
    152 $ flux-capacitor -d 127.0.0.1:10000 -l 127.0.0.1:10001 -n agentA -c
    153 #;> (get-peers)
    154 ((directory 127.0.0.1 10000) (agentA 127.0.0.1 10001))
    155 #;> (define my-callback
    156   (lambda (a b)
    157    (printf "a: ~A, b: ~A ~%" a b)))
    158 #;> (send-to 'directory `(let ((x (lambda (x) (add1 x))) (y (lambda (x) (add1 x)))) (send-to ',(local-node) `(my-callback ,(x 1) ,(y 1)))))
    159 a: 2, b: 2
    160 #;>
    161 
    162 </enscript>
    163 
    164 === Version History
    165 
    166 * v0.1 - Beta Release
    167 
Note: See TracChangeset for help on using the changeset viewer.