Debugging in Flowstone

[martinvicanek]

When you work with FS, you probably spend some time with debugging your schematic. Most people do not really enjoy this activity so they would rather get it over with quickly. Surely there are different ways to approach this, and some are more efficient than others. Therefore I would like to start a discussion on this topic. I certainly would like to spend less time on debugging and more time on creative stuff.

So how do I do it? It depends somewhat on the domain (poly, stream, green, ruby). One general rule is to try avoid introducing bugs in the first place. Or rather, spot them and fix them as early as possible:
- start with a prototype, not the final optimized product
- break it down into small modules and test each module separately
- tidy up your spaghetti connections

Okay so let's assume I have been disciplined and have adhered to my own advice above (which I more often than not don't), but the schematic does not work as desired. What next?
- introduce probes (readouts, analyzer, scope) and work my way down the signal path
- if I use code or assembly, I add a streamout test variable and monitor some relevant points
- isolate the faulty part of my schematic and analyze that part separately so I can mess around without breaking my schematic

So I hope this gets this thread started. I am curious how other people go about deebugging in FS.

[Spogg]

Great advice Martin! You described the process that I eventually arrived at.

My current project is made from 4 separate sub-projects, plus some previous modules I made that I re-worked.

My biggest difficulty is making the child modules look tidy. If you look into my grain players in my Harvester you'll see a total mess that I could see no easy way of making neat. It kinda grew as I solved issues and added extra features. So many interconnections in the end.

Cheers

Spogg

[martinvicanek]

Yes, sometimes it can get messy with a large number of connections. Some things that might help:
- structure your schematic hierarchically.
- keep the number of modules in each unit reasonably low to avoid scroĺing
- consider using wireless connections where suitable.
Wireless connections may sometimes make things worse, though. You have no control of wiring order ( in case it matters). Never use more than one transmitter with the same name. Notice the difference between “ wireless out” and “ module wireless out”.

[adamszabo]

I cant add more to Martins post, its exactly the way to do debugging I usually start deleting things one by one if I find a bug and see where it comes from. If I deleted something and the problem is gone then you can continue to go deeper

[djbrynte]

yep thats how i do it to. otherwise its hopeless. i usually delete module by module and draw the connection to next spot.

And also asaving old project and making a new one. so u dont save over the project u got

[Nubeat7]

in general the most important is a clean and logical structure, so you can find bugs easier. mostly i find small bugs while cleaning up my schematics when i delete every thing which is not needed.

personally i seperate audio, midi, modulation and gui, to seperate gui (only wireless connections) is a very important part for me, like this your dsp and midi parts are so much clearer and you really can focus on the core function of the modules without all the annoying controllers everywhere. also keep modules tidy they always should fit on the screen (in a usable zoomlevel!).

another part to find hidden bugs is optimizing, when you optimize all your modules you need to have a look into every corner of your schematic and test the part you want to optimize, while this again you will find bugs and it also helps to structure your schematic in a more logical way.

the last and maybe most important point is versioncontrol. normally i add every change i did on a list inside the schematic and save the project with a new number, it shouldn't be to much changes in one version specially when you change bigger things. in addition its always good to have a todo list in parallel. often while i'm optimizing my works i come across things i need to do next, to not forget them write em down in your todo list, specially known bugs or important updates and upgrades.

another normally underrated thing is comments, make comments for your self or others when you are working with others, you will not remember any special things 2 years later (me, i dont remember them on the next day ) name your modules in a logical way following the same namescheme. Specially and very important with wireless connections.

the better you follow these guidelines the easier it is to find bugs once they are known.

[tulamide]

the last and maybe most important point is versioncontrol. normally i add every change i did on a list inside the schematic and save the project with a new number, it shouldn't be to much changes in one version specially when you change bigger things. in addition its always good to have a todo list in parallel. often while i'm optimizing my works i come across things i need to do next, to not forget them write em down in your todo list, specially known bugs or important updates and upgrades.

another normally underrated thing is comments, make comments for your self or others when you are working with others, you will not remember any special things 2 years later (me, i dont remember them on the next day ) name your modules in a logical way following the same namescheme. Specially and very important with wireless connections.

I can only agree! Since I was playing "Leisure Suit Larry" in the 80s, I am used to Al Lowe's phrase "save early, save often". About to change an existing method? Try something totally new? Add new stuff? Save, save, save. A simple numbering system is enough to keep control over the files.

Unfortunately, I don't comment enough! I once, after a dozen or so hours of programming without pause, came up with some "genius" code lines. Revisiting them the next day, I couldn't follow them. And I didn't leave a comment. Until today it is code that I use without fully understanding how it works. So, indeed, comment your masterstrokes (which is everything, since you only know what they are later on)!

Martin's summary also is the way to go, when things happened. I hate debugging. Really. I try to program with as much focus as possible to avoid them in the first place. But those, who slip through, are usually a pita. That's why I propose Sherlock Holmes again and again. His methods are just as true for debugging. Usually, you can track it down like that.

Another helpful strategy: Many years ago I discovered the "divide and conquer" algorithm. It is used on arrays a lot. Imagine you have a list of 1 million sorted numbers. Now a new number has to be put at its correct, sorted position in this list. Straight forward, you would compare each value of the list with the new one, until you found the correct position. If you're lucky it's the very first one. But if you have a bad luck day, it is the very last one!
1 million steps would be worst case scenario.
Divide and conquer instead divides the list in two even pieces and checks the last number of the first piece. If your number is higher, it belongs to that piece. So this piece again is divided into two halves. And the process repeats. Even in the worst case scenario you will find the correct position after step 19.
1 million vs 19. The better way is obvious. You can do the very same with your schematic. Delete half of it. If the bug is gone, it's in the deleted half. Reload, delete the other half and again half of the remaining schematic. Repeat until you tracked it down.
This method does not work if a bug is propagated, though. But most of the times it is a helpful way.

[martinvicanek]

Thanks guys, really very good contributions, enlarging the scope of this thread beyond mere bug hunting tips.

Anyway, more specifically about debugging, I think there are different aspects for each domain. Take green for instance. For me the two main sources of problems are:
- wiring order. Sometimes the result depends on the order in which you set up your connections. Triggers will be processed first along the connections that were established first. You can change the order by clicking on a connector that terminates two or more connections, consult the user guide for details. Trigger order is a particularly nasty thing to debug.
- trigger storms. When you have a meshed green topology, chances are that your schematic generates more triggers than necessary, resulting in tasks being executed several times. Often you might not even notice, but it is a waste of resources and can get really bad when you have loops. At each each loop cycle the number of triggers gets multiplied and the result is an exponetially growing avalanche until your computer freezes.

My advice would be: understand triggers, read Trog's Trigger Tutorial, and check your schematic using the stock trigger counter. Avoid unnecessary triggers using trigger blockers etc.

Any Ruby Guru out there willing to comment on debugging Ruby?

[tulamide]

Any Ruby Guru out there willing to comment on debugging Ruby?

Not a guru, yet I can share this:

In terms of debugging, in Flowstone Ruby is just as rudimentary equipped as green or DSP code. Basically you are reduced to the 'watch' method.

But you have better control over when and how to raise exceptions. Instead of just the system defined ones, you can always create your own exceptions and raise them on particular conditions. When not sure about portions of your code, you can use the 'try' block, which will attempt to run the code, raise an exception (also your own ones) if failed and has a section to clean up the remains (for example closing a file that was opened in the try block before its failure).

One concept people might struggle with is the draw order. Drawing is NOT executed immediately. Instead, several draw orders may be buffered, or executed at once. It is even possible that you call a redraw in method a and then in method b, but the drawing occurs as if the order was b, then a.
You can't rely on a draw call being executed right after you raise it. Also, drawing is completely event based and solely in Flowstone's control. When using the 'draw' method, it is just a part Flowstone looks at when redrawing for whatever reason. Say, some window on top of our gui was moved. If your RubyEdit has a 'draw' method, its content will be executed. So stay away from anything else than pure drawing calls. Don't start calculating the average of an array of floats, for example. Do that in other methods and store the result in a class instance variable, to be used by the draw method.

Green trigger avalanches are impacting Ruby as well, if such triggers are connected to a RubyEdit. It will call the 'event' method for each and every trigger!

When the bug is somewhere hidden in your code, best practice is to follow the flow of events. Never assume a certain flow, but really follow it right from the start. The 'watch' method can help a lot with it. Say you expect a certain value of a variable. Place 'watch' orders for that variable in all of the methods and you quickly see at what point the variable differs from what you expected.

Stay away from deep nested recursions. Ruby's stack might get overloaded, and Flowstone uses a quite aggressive timeout system to prevent audio drops. You can do recursions, but they should be flat and on a small count basis (some hundred iterations should be fine).

Use 'inspect' or 'to_s'. Sometimes classes change (an fixnum might become a float, a string might become nil, etc.), and if you don't pay attention to that, you might end with error messages that don't make much sense. 'inspect' then will give you a hint on class types. Also, in live code you can check for class equality ('===', 'is_a', and other methods) to prevent such errors. Or handle all possible class changes.

The nastiest bugs are those that don't raise an exception, yet give strange results. Mostly this is caused by inaccuracies of the code. You may use 'watch' once again, setting it to tell you if certain methods or conditional branches are executed. You can also setup globals, but you HAVE to make sure, they are deleted before release. You can also use a class running alongside your flow of events, collecting all kinds of data that you can inspect afterwards.

And always work concentrated. The more accuracy, the less bugs.