Right now we have only one registration apart from the people above and myself – so come on

Time and date: May 12th, Thursday 19:15 – 20:15 / Location: Room 202
Location: GOTO Copenhagen 2011 takes place in Radisson Blu Falconer Hotel & Conference Center

Info and registration: http://gotocon.com/cph-2011/presentation/UserGroup-Meeting:%20Clojure%20stars%20and%20you

To start with something that wasn’t too complex, I decided to try and create a parallel version of mapping a function for vectors, i.e., an eager function that would take a vector and a function as input and produce a mapped vector as output (instead of a seq). This would replace a pattern I’ve often used:

(into [] (map f vs))

with (vectormap f vs), which avoids the overhead of constructing a seq and the reconstructing a vector by conj’ing from the seq.

My initial goal was to produce a parallel version e.g., (pvectormap f vs). As Rich has pointed out: Clojure’s persistent data structures are excellent candidates for parallel processing using divide and conquer since they are trees which are already “sitting there divided!” Further immutability means no synchronization is needed. For example, remember that PersistentVector is a balanced 32-way tree consisting of size 32 arrays of Objects (Nodes in the tree or the actual values stored in the vector).

I decided to warm up by implementing vectormap, i.e., the serial version, first.

Remember this?

Apparently Rich Hickey presented this piece of code at JVM Lang summit:

static public Object ret1(Object ret, Object nil) {
    return ret;
}

public static int count(Object o){
    if(o instanceof Counted)
        return ((Counted) o).count();
    return countFrom(Util.ret1(o, o = null));
}

Has Rich gone mad? A two argument static method which simply returns the first argument?? When I first read Ola’s blog post I simply couldn’t figure out why he would use that code… However, when I was writing the vectormap code I was thinking: suppose the input vector is really large — in fact, so large that we don’t have memory enough to hold both the input and the output vector. Then vectormap would produce an OutOfMemoryError. But suppose the calling code didn’t actually need the input vector what if we would release references to the elements of the input vector as we construct the corresponding mapped elements in the output vector (but without destroying the input vector)? We would need to only keep references to Node vectors we hadn’t already processed, and then null out our local variables to those we had.

This was when I realized that this is exactly what Rich’s function can help with: when calling the countFrom function, he provides as argument the seq referenced by the local variable o via the ret1 function. The side effect of using ret1 is that since Java is strict, both argument expressions to ret1 are evaluated (left-to-right), and consequently o is null’ed out. No more holding on the the head I could use this to only hold on to the vector arrays I hadn’t processed.

For example:

private static Node mapNode(IFn f, Node node, int level) {
	if (node == null) {return null;}
	if (level == 0) {
		return new Node(null,mapArray(f, Util.ret1(node.array, node=null)));
	}
	Object[] newArr = new Object[node.array.length];
	System.arraycopy(node.array, 0, newArr, 0, node.array.length);
	node=null;
	level -= 5;
	for (int i=0;i<newArr.length;i++) {
		newArr[i] = mapNode(f,Util.ret1((Node) newArr[i], newArr[i]=null),level);
	}
	return new Node(null,newArr);
}

This code is available in my clj-ds project.

Parallelize with Fork/Join

The pvectormap function uses Fork/Join to parallelize the mapping. I’m not sure about the granularity of the tasks, but I decided that processing a size 32 array was too small a task, and went with processing 32 size 32 arrays instead.

Starting at the root array of nodes, the code simply forks 32 tasks which recursively process each child of the root. This forking continues recursively until we hit the second lowest level in the tree — this is processed sequentially using the mapNode function from above. This is implemented as a RecursiveTask in the Fork/Join framework.

static final class PMapTask extends RecursiveTask<Node> {

	private IFn f;
	private int shift;
	private Node node;

	public PMapTask(IFn f, int shift, Node node) {
		this.f = f;
		this.shift = shift;
		this.node = node;
	}

	public Node compute() {
		if (node == null) {
			return null;
		}
	   if (this.shift <= 5) {
		   return mapNode(f,node,shift);
	   }

	   PMapTask[] tasks = new PMapTask[node.array.length];
	   shift -= 5;
	   for (int i=0;i<tasks.length;i++) {
		   tasks[i] = new PMapTask(f,shift,(Node) node.array[i]);
	   }
	   invokeAll(tasks);
	   Node[] nodes = new Node[node.array.length];
	   try {
		   for (int i=0;i<tasks.length;i++) {
				nodes[i] = tasks[i].get();
		   }
		   return new Node(null,nodes);
	   } catch (InterruptedException e) {
			Thread.currentThread().interrupt();
			throw new RuntimeException(e);
		} catch (ExecutionException e) {
			throw new RuntimeException(e);
		}
   }
}

On my dual core system with a non trivial function f that actually does some work, using pvectormap is about twice as fast as vectormap: see PersistentVectorTest of clj-ds.

Next stop: optimize and add vectormap and pvectormap to Clojure core

https://secure.trifork.com/aarhus-2010/freeevent/index.jsp?eventOID=2713

I really wanted to focus on the core of Clojure: things like time/state management, functional programming, programming to contracts, meta programming, host interop, dynamics, interactivity and expressive power. I want people to see what Clojure is without being blinded by what is a mental blocker for some: the parentheses.

So as a fun exercise, I decided to remove (almost) all parentheses from code on my slides. As it turns out, the code looks much like ruby or python (just more functional and concise). All code on my slides can be turned into real Clojure code by inserting parens appropriate places (newlines and indentation help with “visual parsing”). The “commas are whitespace” is used to make it more readable (for comma-liking eyes). Obviously as we go into meta programming with macros this breaks down, but that is the last topic of the talk

slides

Github repos:

http://github.com/krukow/swing-demo

http://github.com/krukow/ants-demo
http://github.com/krukow/clojure-circuit-breaker

Examples (I know the semantics aren’t exactly the same, but I am considering syntax here).

ruby-1.9.2-p0 > def m
ruby-1.9.2-p0 ?>  {:name => "Karl", :age => 42}
ruby-1.9.2-p0 ?>  end
ruby-1.9.2-p0 > m
 => {:name=>"Karl", :age=>42}
ruby-1.9.2-p0 >

user> def p
         {:name "Fred", :age 42}
#'user/p
user> p
{:name "Fred", :age 42}

ruby-1.9.2-p0 > class Person
ruby-1.9.2-p0 ?>  attr :name,:age
ruby-1.9.2-p0 ?>  attr_writer :name,:age
ruby-1.9.2-p0 ?>  end
ruby-1.9.2-p0 > p = Person.new
 => #
ruby-1.9.2-p0 > p.name="fred";p.age=42;
ruby-1.9.2-p0 > [p,p,p].map &:name
 => ["fred", "fred", "fred"]

user> map :name [p,p,p]
("Fred" "Fred" "Fred")
;;or
user> defrecord Person [name,age]
user.Person
user> def p
         Person. "Fred", 42
#'user/p
user> map :name [p, p, p]
("Fred" "Fred" "Fred")

ruby-1.9.2-p0 > [p,p,p].map(&:age).reduce(&:+)
 => 126

reduce +
   map :age [p p p] => 126
;;or
->> [p p p]
          map :age
           reduce +

A lot of interesting things have happened with data structures in JVM-land since then: Erjang uses Clojure’s data structures, it looks like Scala is porting PersistentVector, upcoming Seph is using them too. My clj-ds project should help in this regard: I’ve extracted the data structures of Clojure from its compiler for use with JVM-based languages (providing some extra stuff like reverse and “positioned” iterators). There are already people interested in using this in Java land.

Some people have asked for the “part ii” post, and my son just fell asleep, so … Most of what is described in the PersistentHashMap post is still true, however there have been optimizations and simplifications which I explain here. Note: before reading this post, you should read the previous post on PersistentHashMap.

First, some changes. Previously there were five implementations of the INode interface; this has changed and there are now only three implementations: ArrayNode, BitmapIndexedNode and HashCollisionNode. This means that: EmptyNode, LeafNode, FullNode are out, with ArrayNode replacing FullNode. An array node is an array where the entries are null or instances of INode, i.e., it stores other nodes but not any key-value pairs. An empty persistent hash map is simply a persistent hash map where the root node is null — this removes the need for EmptyNode. Finally, leaf nodes used to store the actual entries stored in the map. Leaf nodes are out, and instead BitmapIndexedNodes directly embed the map entries in their arrays.

The idea is the following: if, in the old implementation, a BitmapIndexedNode would store a leaf node at an index, then instead, it now embeds the key and value directly in its array. This array used to be of type INode[], storing only nodes, but is now a mixed object array for which the value can be one of: a map key, a map entry, null or an INode object.

The above drawing corresponds to the old structure. In the new structure all the white circles (the leaf nodes) are embedded directly in their parents.

There is an invariant:

for all the indices that are in the bitmap, the even indices store keys or null; the odd indices store values or INode objects. Key-value pairs are layed out in sequence, so that if index 2*i is a key then index 2*i + 1 is a value. If an index 2*i is null then 2*i+1 must be a non-null INode object.

Note: if you don’t remember how bitpos, bitmap and index work see the part i post.

The strategy used in BitmapIndexedNode is that it can store up to 16 entries in the bit map: if the size grows above 16, it is converted to a FullNode.

Assoc. The assoc method creates a persistent hash map which is like the current one, except that it additionally stores another map entry. As before assoc works using path copying: all that is changed in the new map is the path from the root node to the newly added map entry.

Beware: the following drawing looks confusing: take the time and read the explanation. It is showing two persistent hash maps, where one is obtained by assoc’ing to the first. Again this is a modified version of one of Rich’s slides.

The first map is rooted on the left (where the left-most box points to). The second is rooted where the right-most box points to. The nodes are grouped in three, each indicated by a colored circle that surrounds it. The new node is in the right-most, lower corner.

Purple is the path in the old tree to where the new map entry would be;
green is the new nodes that are created in the new hash map.
The dashed lines indicate that the nodes in the new tree share children with nodes in the old tree. The red circles show all the nodes that are shared in the tree: note that this is most of the nodes.

So how much work needs to be done to create the new tree? Suppose we are storing key k with value v. Using recursion, descend down the original tree as if looking for the key k. The key k isn’t found. In the worst case this takes time: O(log₃₂ n), in practice it we could stop at any level in the tree so 2-3 steps would be common (remember from the old post that the work done at each level is constant and fast). At the bottom we create a new BitmapIndexedNode and store the new map entry in it. If the bottom node in the old tree was a BitmapIndexedNode with less than 16 elements the new BitmapIndexedNode is a copy of the old one, except that the new map entry is added. This step takes constant time since the array to copy at the bitmap indexed node always has less than 32 elements (because we store at most 16 map entries as: key, value, key, value, …). If the bottom node was an ArrayNode we simply copy the array node, and make the new BitmapIndexedNode a size-one child of this array node (still constant time).

On the drawing above, we have now recursively descended the purple path in the left/old tree, and we have created the new node which is a bitmap indexed node. What remains is to establish the path to this new node, in the new tree: this path is almost identical to the “purple” path in the old tree: the only difference is that we have created a new bitmap indexed node. The parent of the new node must of course reference it, so that is copied and modified to get a reference to the new node. This means that we must also copy the grandparent of the new node, modifying it to reference the parent. And so on… This copying takes place on our way “up” through the recursion, i.e., after the recursive calls complete at each node level.

Let’s decompose the code. We only look at assoc for BitmapIndexedNode as it is the most interesting.

public INode assoc(int shift, int hash, Object key, Object val, Box addedLeaf){
		int bit = bitpos(hash, shift);
		int idx = index(bit);
		if((bitmap & bit) != 0) {
			//..
		} else {
			//
		}
}

This should be familiar from the previous post: we check if the index of the hash (at the current level) is in the bitmap. The else branch is the case where the index is not in the bitmap, corresponding to reaching the bottom of the path: here we must create a new node and path-copy as described above. In the “if”-branch we simply either call recursively if the index references an INode: if it references a key-value pair this is a “replace” and we do path copying here too. Again we look only at the else-branch as it is the most interesting.

public INode assoc(int shift, int hash, Object key, Object val, Box addedLeaf){
		int bit = bitpos(hash, shift);
		int idx = index(bit);
		if((bitmap & bit) != 0) {
			//..
		} else {
			int n = Integer.bitCount(bitmap);
			if(n >= 16) {
				//convert to ArrayNode
			} else {
				Object[] newArray = new Object[2*(n+1)];
				System.arraycopy(array, 0, newArray, 0, 2*idx);
				newArray[2*idx] = key;
				addedLeaf.val = addedLeaf; 
				newArray[2*idx+1] = val;
				System.arraycopy(array, 2*idx, newArray, 2*(idx+1), 2*(n-idx));
				return new BitmapIndexedNode(null, bitmap | bit, newArray);
			}
		}
}

Remember (from the previous post) that Integer.bitCount(bitmap) counts the number of children of this node. If we are storing less than 16 elements, we have room for one more: To create the new bitmap indexed node simply copy the object array, and modify it to store the new key-value pair (using the invariant mentioned above). (Ignore the “box” part, it is used to communicate to higher-levels in the recursion what happened.) Finally, if we have 16 elements stored already, convert to an ArrayNode:

public INode assoc(int shift, int hash, Object key, Object val, Box addedLeaf){
		int bit = bitpos(hash, shift);
		int idx = index(bit);
		if((bitmap & bit) != 0) {
			//..
		} else {
			int n = Integer.bitCount(bitmap);
			if(n >= 16) {
				INode[] nodes = new INode[32];
				int jdx = mask(hash, shift);
				nodes[jdx] = EMPTY.assoc(shift + 5, hash, key, val, addedLeaf);  
				int j = 0;
				for(int i = 0; i < 32; i++)
					if(((bitmap >>> i) & 1) != 0) {
						if (array[j] == null)
							nodes[i] = (INode) array[j+1];
						else
							nodes[i] = EMPTY.assoc(shift + 5,  Util.hash(array[j]), array[j], array[j+1], addedLeaf);
						j += 2;
					}
				return new ArrayNode(null, n + 1, nodes);
			} else {
				//we covered this...
			}
		}
}

The first block up to the ‘for’ loop prepares the array of INodes that will be the children array of the new ArrayNode. We create a new BitmapIndexedNode easily by calling assoc on an empty persistent hash map (which is an easy way of creating an one-entry BitmapIndexedNode). Note that the indexing strategy for ArrayNodes is different from BitmapIndexedNode: we don’t need the bitmap We simply use the 5-bit block corresponding to the level (again see the older post).

Finally, the for-loop copies all the other nodes that are stored in this bitmap indexed node into the new array node. This entails mapping between the bitmap index scheme and the “5-bit hash-block” scheme. For each possible index in the bitmap node, only do work if the index is present in the bit map: if(((bitmap >>> i) & 1) != 0). The variable j runs through the even indexes, and according to the invariant: null means that j+1 is an INode, and non-null means it is a value in a map entry.

I am wondering if there is an optimization possible here? We are looping through all possible indices of the new ArrayNode, but we know that we only have to do something on the indices that correspond to an non-zero index in the bit map; and there can be only 15 of those… Would it be possible to iterate only those using some strategy? If I figure something out, I’ll let you know

This post describes some mistakes I’ve made in the Clojure circuit breaker project, and how I managed to fix them, mostly due to guidance from Christophe.

The following is an (embarrassingly long) list of issues that my previous version of circuit breaker had. I think others can learn from my mistakes.

Platform speed protocol functions. In order for a protocol function reaching a datatype to run at platform call-speed, the datatype must inline the protocol implementation. In the old version, I extended the state transitions protocol to the circuit breaker states using (extend …): this is usually 3-4x times slower than platform-speed method calls (but can be much slower when cache misses). I now inline the protocol extension to the states.

This inlining gave a new problem. I had two data types, say A and B, where A creates an instance of B and B creates an instance of A in the implementation of the inlined protocol functions. You can’t have this type of “mutually recursive data types” since they are compiled on the fly to Java classes. The fix was to…

Create factory functions for your data types. There are at least two reasons for this. First a factory function can do processing of its arguments (e.g. pre condition), say for validation. The data type constructors can’t have any logic. Second, as noted by Alex Miller on his blog: to use data types defined in another namespace you must import them. But you can use require/use to bring the factory functions into your namespace.

I thought I knew: protocols aren’t interfaces (and Java interop).. I used a protocol: CircuitBreakerTransitions to model the states. The protocol contains functions needed for state transition on various events. I extended the protocol to my states, e.g.,

(defrecord ClosedState [policy fail-count]
  CircuitBreakerTransitions
  ...)

It inlines the protocol so the generated class implements the protocol’s backing interface: It’s fast and works great.

The problem appeared when I wanted to expose a Java API for the circuit breaker: one of the API methods getCurrentState returns the current state – now, the question is what is its signature? My first attempt was public CircuitBreakerTransitions getCurrentState(). Now what is wrong?

The problem is that my protocol can be extended to reach other types. Those types may or may not inline the protocol functions, and hence it is possible for the protocol to reach a type which doesn’t implement the CircuitBreakerTransitions interface… So should I just return “Object” – that isn’t really useful.

I haven’t implemented a solution yet, but this is what I am thinking. Keep the type: CircuitBreakerTransitions getCurrentState(), but in my Java-interop (gen-class), the function that implements getCurrentState should grab the state s from the circuit breaker. Now I know that (satisfies? CircuitBreakerTransitions s) is true, but (instance? (:on-interface CircuitBreakerTransitions) s) may be false. If it is true, I simply return it. Otherwise: reify CircuitBreakerTransitions by delegating to the protocol functions on s. This may sound a bit wierd at first, but I think of it like creating a new object that satisfies the interface by dynamically dispatching to s.

Type-hits are for removing reflection, not enforcing type safety My first iteration tried to type-hint the records, e.g.,

(defrecord ClosedState [^TransitionPolicy policy ^int fail-count])

This is just plain terrible First, those hints are ignored (but may be used in later versions of Clojure). Second, int isn’t suported in the current version of Clojure. Third, TransitionPolicy is a protocol – and, yes, protocol’s aren’t interfaces (see above): problem being again if I supply an object that satisfies the protocol but doesn’t implement the backing interface. Ugh.
The reason I put the hints wasn’t to remove reflection, it was for the generated constructor to have types (which is a valid thing to want, but unsupported now). But it is the wrong approach for the reasons above.

The right thing is to remove hints and expose a factory function which checks that the first argument satisfies the TransitionPolicy protocol and that the second argument is non-negative.

Premature optimization. My circuit breaker implementation tried to optimize a corner-case for the swap! function: suppose you (swap! state f) and f applied to the current state is identically the same state. Then there is no reason to do a compare-and-set!. My transition-by! function implemented this optimization. However, this was a premature optimization that changes the semantics of time (wow, Clojure really is powerful ). The fundamental question is this: [s] -f-> [s] (where s is a state and f is a side-effect free function that advances time), is this transition really advancing time? (it isn’t observable, is it?…)

Anyway, I’ve never benchmarked the code so it was a premature optimization leading to less understandable code. Also, as Jacob and I discussed in the plane home: it actually skews the behavior of the circuit breaker to prefer switching states rather than staying in the same state – something that you may or may-not want.

Finally an off-topic: It is now possible to build the Clojure circuit breaker including AOT compilation of Java interop classes. I ran into a problem with lein where the order of namespaces in :namespaces isn’t preserved. This is a problem when you are gen-interfacing in one file and gen-class :implements that interface in another.

I’ve created a very simple patch to lein to preserve the order.

http://blog.higher-order.net/wp-content/uploads/2010/07/0001-don-t-convert-namespaces-aot-to-a-set-as-it-does-n.patch.txt

Phil is applying this patch so it should be out soon. Until then, if you don’t want to patch lein, there is a step-by-step guide to repl AOT compilation in the README.

Those interested can grab the latest code.

http://github.com/krukow/clojure-circuit-breaker

There are many advantages to programming with persistent data structures (which implies immutability) but that isn’t the topic of this post… Currently the Clojure data structures are implemented in Java, so in principle they should be usable also outside of Clojure, say from Java. However, in practice it is inconvenient (see below).

I’ve created the project clj-ds to make Clojure’s data structures available in a more practical form to other JVM languages than Clojure. The README file from the clj-ds GitHub project explains the motivation:

Advantages of clj-ds when constrained to working with Java (as opposed to just including clojure.jar)

* Currently the Clojure data structures are implemented in Java. In the future,
all of Clojure will be implemented in Clojure itself (known as “Clojure-in-Clojure”).
This has many advantages for Clojure, but when it happens the data structures will
probably be even more intertwined with the rest of the language,
and may be even more inconvenient to use in a Java context.

The clj-ds project will maintain Java versions of the code, and where possible attempt
to “port” improvements made in the Clojure versions back into clj-ds. Thus keeping maintained
versions of the Java data structures.

* In the current Clojure version, calling certain methods on PersistentHashMap requires
loading the entire Clojure runtime, including the bootstrap process. This takes about one second.
This means that the first time one of these methods is called, a Java user will experience a
slight delay (and a memory-usage increase). Further, many of the Clojure runtime
Java classes are not needed when only support for persistent data structures
is wanted (e.g., the compiler).

* The clj-ds library is not dependent on the Clojure runtime nor does it run any
Clojure bootstrap process, e.g., the classes that deal with compilation have been removed.
This results in a smaller library, and the mentioned delay does not occur.

* Clojure is a dynamically typed language. Java is statically typed, and supports
‘generics’ from version 5. A Java user would expect generics support from a Java
data structure library, and the Clojure version doesn’t have this.
clj-ds will support generics.

* Finally, a slight improvement. Certain of the Clojure data structure methods use Clojure’s ‘seq’ abstraction. In the implementation of the Java ‘iterator’ pattern. It is possible, to make
slightly more efficient iterators using a tailor made iterator. clj-ds does this.

Code: http://github.com/krukow/clj-ds

What? From the Stomp website:

Stomp provides an interoperable wire format so that any of the available Stomp Clients can communicate with any Stomp Message Broker to provide easy and widespread messaging interop among languages, platforms and brokers.

As mentioned, this includes JMS. Stomple is a JavaScript library which enables using browsers that support WebSockets as messaging clients, e.g., subscribing to an JMS topic in a JavaScript program running inside Chrome.

Websocket communication has less overhead than HTTP when HTTP semantics aren’t needed. More importantly, WebSockets allow the server to push updates to the browser (as opposed to the usual HTTP request-response paradigm). For a simple example, see the screen cast of the “transactional chat example” where chat messages are pushed from the server to participating clients.

Why release Stomple when there is already stomp-websocket? First of all, Jeff did an excellent job with stomp-websocket. However, I wanted additional features and more production maturity (e.g., support for timeouts, various low- and high-level callbacks and automatic receipts).

A few notable features:

• Customizability and Callbacks. A key value of Stomple is that it shouldn’t cut off access to any low-level functionality. Hence everything is customizable and accessible to the user code. All core functions support success and failure callbacks. Further, there are low-level callbacks: socketOpen, socketMessage, socketClose, socketError corresponding to the low-level websocket events. These can be used to customize behaviour for special use-cases. At a higher-level, there are callbacks onConnect, connectFailed, onError, onReceipt correspoding to the Stomp events.
• Automatic receipts. If client.autoReceipt is true (which it is by default), then all Stomp messages sent to the server include an automatically generated ‘receipt’ header. In the Stomp protocol, this causes the server to send a receipt for each message it receives, hence reassuring that the message has been received. If not enabled, the client can’t be sure the message is actually received.
• Timeouts. By default all messages sent to the server are associated with a (configurable) 8 second timeout. So for example, suppose you subscribe to a destination, but do not receive a server receipt within 8 seconds: then your failure callback is called with reason ‘timeout’ and information about the message that failed. This way you are guaranteed that either your success or failure callback will always be called (but not both ). These time-outs are pervasive and configurable per API call.
• Transaction management. In Stomp, transactions are started using the ‘BEGIN’ frame, corresponding to a begin function in Stomple. When you call begin, you don’t have to specify a transaction-id: if you don’t, one will be generated automatically for you. Further, any API calls made between a begin and a commit/abort automatically use this transaction identifier, hence grouping the calls in the same transaction (unless, of course, you explicitly provide a different or no transaction id). Further, this nests arbitrarily, and works in a stack-like manner (e.g., begin, begin, send, associates send with inner-most begin).
• Feature complete. Stomple aims to be feature complete. For example, it supports the recommended Stomp ‘content-length’ header, where the current stomp-websocket version does not.
• Correctness. Stomple is tested manually and has a growing automatic test-suite written in YUI3-test. Stomple passes JSLint.

I decided not to build on Jeff’s library because when APIs become more complex, I prefer using configuration-objects since it makes code more readable and easy to maintain (most Stomple functions take a single object literal parameter which names the function’s “many arguments”).
For example to create a Stomple client and to configure it to use destination ‘jms.topic.chat’ as default use:

var client = Stomple.create_client({
    url : "ws://localhost:61614/stomp",
    destination : "jms.topic.chat",
    login : "guest",
    passcode : "guest"
});

A different example of using single-argument configuration objects would be subscribe:

client.subscribe({
    success: function(frame) {//called if subscribe succeeds within timeout-period
        //subscribe succeeded... do something
    },
    failure: function(spec) {//called if subscribe fails or times out
        console.log(spec.reason);
    },
    handler: function(msg) {//called when a message arrived ('this' is scope - see below) 
        this.received = msg.body;//"this" is "someObject"
    },
    scope: someObject
});

Note by the way that if client.autoConnect is true (which it is by default), then you don’t have to explicitly connect. Stomple will automatically connect upon your first action. The subscribe function supports an optional destination parameter in-case a default wasn’t supplied when the client object was created (or in case you want to subscribe to a non-default destination).

How?
For each Stomp client frame (command): SEND, SUBSCRIBE, UNSUBSCRIBE, BEGIN, COMMIT, ABORT, ACK, DISCONNECT there are corresponding lower-case functions on the client object, e.g., send, subscribe… Defaults are specified when creating the client object. For example.

var client = Stomple.create_client({
    url : "ws://localhost:61614/stomp",
    destination : "jms.topic.chat",
    login : "guest",
    passcode : "guest",
    autoConnect: true,//which is actually the default
    timeout: 3000,
    autoReceipt: true//which is actually the default
    //...
});

See Stomple.ClientPrototype for all overrides.

Once a client object is created, the user can issue commands. For example, in the chat example a typical sequence would be.

client.subscribe({
    handler : function(msg) {//update screen on chat msg receiption
	    var c = document.getElementById('content');
	    c.innerHTML = c.innerHTML + '<br>' + msg.body;
	},
	scope : anObjectIfNeeded,
	success : function() {// did subscription succeed?
        //send a test message
        client.send({
            body: "User krukow joined chatroom #stomple",
            success: function() {
              console.log("sent welcome message...");          
            },
            failure: function() {
              console.log("Failed...");
            }
            
        });
	},
	failure : function() {// did subscription fail?
		console.log("sub fail");
	}
});

Things are pretty straightforward from here (if you get Stomp ). For more advanced examples see the automated test-suite. Here is an example of a transaction.

this.client.begin({
    failure: function() {
        Y.Assert.fail("Begin transaction failed.");
    },
    success: function(){ 
		for (i=0;i<N;i+=1) {
			this.client.send({
				body: ""+msgBodies[i],
				failure: sendFailed
                //we don't wait for receipts here... Socket provies order..
			});
		}
        this.client.commit({
            failure: function() {
                Y.Assert.fail("Commit transaction failed.");
            },
            success: function(){//...
            }
        });
    }
});