Stack Messages in Lacewing

From FusionWiki

Usage of Stack Messages

Since they're something I'm often being asked about, and something not many people seem to understand, in this article I'm going to explain how stack messages work in Lacewing.

Why Should I Use Stack Messages?

I guess if you're reading this article, you're probably currently doing things the Moo way and sending delimited strings to be parsed on the receiving end with String Parser. Let's imagine we have a networked application that has to send two numbers (perhaps X and Y coordinates?) - it sends them like this:

104,178

That string is 7 characters in length, which means Lacewing will use (excluding headers) seven bytes of bandwidth to transmit it. If we were using stack messages instead, this could be sent with TWO bytes of bandwidth (or four if the numbers were larger than 255).

How? Well, each character in a string (letter, string, or number) is represented by an ASCII number (search for an "ASCII table" to see which numbers are used for different characters). The character that represents the number "1" is character number 49, the number "0" is character number 48.

To send a string, Lacewing uses 1 byte (a byte can be any number from 0 to 255) per character. So the string above would be sent like this:

Which means the seven bytes:

are transmitted. This is obviously a complete waste of bandwidth, because all we want to send is two numbers (104 and 178). Lacewing, thankfully, allows you to send the numbers directly, instead of sending a string, and that's the stack messages. That means you can send these bytes instead:

and read them on the other end. Considering how frequently you're likely to be sending messages, this is a huge bandwidth saver.

How do I use stack messages?

Well, I guess we'll just cut to the chase. Below I'll show an example of how to send the two numbers we were talking about above, and read them on the other end.

Sending the stack message

Old code

Lacewing : Send text Str$(104) + "," + Str$(178) to channel on subchannel 0

New code

Lacewing : Push byte 104 Lacewing : Push byte 178 Lacewing : Send stack to channel on subchannel 0

Receiving the stack message

Old code

+ On text channel message on subchannel 0 - String Parser : Set source string to Received$("Lacewing") - Active : Set X position to Val(listGetAt$("String Parser", 0)) - Active : Set Y position to Val(listGetAt$("String Parser", 1))

New code

+ On stack channel master on subchannel 0 - Active : Set X position to Byte("Lacewing", 0) - Active : Set Y position to Byte("Lacewing", 1)

And that's about it, as far as sending and receiving a message composed of bytes goes. Here's the catch:

A byte can only hold a value from 0 to 255 (when you use the expression to read it as unsigned) or from -128 to 127 (when you use the expression to read it as signed). If you want values beyond this range, you'll have to use one of the other data types.

Lacewing allows you to write and read the following types from stacks:

It's really easy to understand how to use all of these types in your stack messages - you just have to understand how the stack works. When you "push" something onto the stack, it gets added to the end. So:

You could now send the stack, and then on the receiving end, read the respective type at the respective index. So if you read an integer at 3, you'd get 31333337. If you read a byte at 7, you'd get 100. Basically, the position of everything in the stack starts at 0 (the first thing you push will always be at 0) and from there, depends on how big the things you pushed afterwards were.

If we sent the stack above, containing the numbers 3, 572, 31333337 and 100, it would be 7 bytes in size.

If you sent this as a delimited string: 3,572,31333337,100

That's 18 bytes total. This should give you an impression of how much space you can save using the stack messages under Lacewing.

I hope you enjoyed the article, and I hope if stack messages previously made no sense to you, that they make a little more now. Good luck :)