Project

Topics

Namespaces

Public Vars

lotuc.xnfun.api

Cross Node Function API.

Checkout lotuc.xnfun.core.node for the node abstraction.

API summary

Example

(def node-42 (start-node {:node-id "node-42"
                          :transport
                          {:xnfun/module 'xnfun.mqtt
                           :mqtt-topic-prefix ""
                           :mqtt-config
                           {:broker "tcp://127.0.0.1:1883"
                            :client-id "node-42"
                            :connect-options {:max-in-flight 1000
                                              :auto-reconnect true}}}}))

(add-function node-42 "add" (fn [[x y]] (+ x y)))

@(call node-42 "add" [20 22])

(stop-node node-42)

add-function

(add-function node fun-name fun & opts)

Register a function to given node.

Arguments:

  • node: The node started with start-node
  • fun-name: The function name
  • fun: Can be either a one argument or two arguments function
    • (fn [arg] ...)
    • (fn [arg {:as call-options :keys [in-c out-c req-meta]}] ...)
      • :in-c: A channel through which callee can receive message sent from caller. Check call-function for details.
      • :out-c: A channel through which callee can send message to caller. Check call-function for details.
      • :req-meta: {:keys [req-id timeout-ms hb-interval-ms hb-lost-ratio]}, all of these fields are optional
        • :req-id: The call request’s id
        • :timeout-ms: The call requests’ timeout (in ms)
        • :hb-interval-ms: The expected heartbeat interval (in ms)
        • :hb-lost-ratio: If the :hb-interval-ms given, the caller will consider the request dead when no heartbeat received in (* hb-interval-ms hb-lost-ratio).
  • opt: {:keys [overwrite]}
    • overwrite: defaults to be true; if specified as false and the given name is already registered, the function will throw.
view source

call

(call node fun-name fun-params & {:as options})

This is a wrapper of call-function for the simplest use case.

Consider the same as (future (apply fun fun-params)) in which fun represents the function associated with function name fun-name.

view source

call-function

(call-function node fun-name fun-params & {:as opts, :keys [req-meta out-c]})

Call the function through given node.

Returns {:keys [res-promise request]}

  • :res-promise: A Clojure promise for the call result {:keys [status data]}.
    • :data is the value of function call return value if :status is :ok.
    • :data is the data representing a call failure if :status is not :ok. There are now three types of error :status:
      • :err The callee function’s execution error (mean user code erro, no matter if it’s executed locally or remotelly).
      • :xnfun/err The caller side XNFUN node error (ex, timeout)
      • :xnfun/remote-err The callee side XNFUN node error (ex, timeout)
  • :request: The call request {:keys [fun-name params req-meta in-c out-c]}.
    • req-meta: check add-function’s fun for details.
    • in-c: A channel through which caller can send message {:keys [typ data} to callee. Now there are two types (encoded in :typ) of data can be sent:
      • :xnfun/to-callee: The message is forward directly to callee.
      • :xnfun/cancel: The message is forward to callee as well, the callee can do a gracefully shutdown on it. XNFUN will also forcelly cancel the request.
    • out-c: A channel through which caller can receive message {:keys [typ data]} from callee. Now there are two types (encoded in :typ) of messages:
      • :xnfun/to-caller: The message is forward from callee directly
      • :xnfun/hb: The message is forward from callee as well, callee can send and type of :data as the heartbeat content. XNFUN will ignore data part, and just reset the internal heartbeat check timer.
view source

make-node

(make-node {:as node, :keys [node-id node-options]})

Create a xnfun node.

Check lotuc.xnfun.core.node-defaults for node-options defaults.

  • node-options
    • hb-options:
      • :hb-interval-ms: Heartbeat interval for this node.
      • :hb-lost-ratio: Consider this node to be heartbeat lost in (* hb-lost-ratio hb-interval-ms) when no heartbeat occurs.
    • :transport: The transport this node would make to connect to other nodes. Check transport configurations for details.

Transport configurations

{:xnfun/module 'xnfun.mqtt ;; we only support mqtt yet.
 :mqtt-topic-prefix ""
 :mqtt-config {}}

Check lotuc.xnfun.core.transport-mqtt/make-mqtt-transport for mqtt-config.

view source

start-node

(start-node {:as node, :keys [node-id node-options]})

Create a node and start transports & remote node monitoring & call handling.

view source

stop-node

(stop-node node)

Stop the node started with start-node.

view source