bluespec.com

[chris]

When I started to write my post reviewing the behaviour of readable object, I had a feeling of being lost whenever using them in more sophisticated manner. I often had to guess or even brute force expressions involving them until the they where accepted by the compiler.

After doing my investigations and reading the concise specification of the mechanism from stoy, this doesn't seem to apply any more. So my problem might have been only a lack of deeper knowledge of the type system.

After being pointing out once again that the type system is based on Haskell I started to finally read about it. It helped me to make sense of what I already knew from BSV, like type classes and provisos. Furthermore instead of just using it, I learned to appreciate it now after knowing what the type system is capable of and that it is as sophisticated as necessary and no more. (A nice introduction can be found starting here)

How the type system was introduced to me:

I know Bluespec already advertises it's type system, but when you look in the documentation, there isn't much. In the "BSV by Example" guide you learn about the basic types at the very beginning and later about Polymorphism and how to construct enum, struct and union based types. However the real power of the type system, type classes, are solely explained in the Reference Guide and there under "Advanced topics", with the disclaimer:

[stoy]

Chris wonders whether Bluespec Inc. might be less "discouraging", in the official documentation, about advanced features such as typeclasses. He suggests that to use BSV well one needs to understand it, and that means being aware of all its features and how they are structured together into one coherent whole. Of course, from the ideal point of view he's right. And in fact learning any language is a non-terminating process -- one gets better at it all the time. That's also true about languages like English, or music (compare late Mozart with his earlier writing). The question is, how much is enough to get started effectively? And then, what resources are there, or should there be, for our users to do "lifelong learning", and what can the Company (with its limited resources) do to help?

Our position is that designers can use BSV pretty effectively after a training lasting just two or three days. And that's the kind of training we normally offer -- it sometimes expands to a week or so if we're also helping the trainees get to grips with their first project. In a training that short there's simply not time to cover everything. We feel that the most important thing to emphasize in our training is the concept of atomic transactions, as used in our rules and interface methods; and the idea that although many rules fire in a single clock cycle, the overall effect is as if they happened one at a time, in the so-called "logical execution order". We hope that other high-level features, which we don't have time to cover, will be gradually picked up later, as the designer's experience grows.

Our "BSV By Examples" book, too, is designed to help new users by showing them BSV in action, and giving them templates for dealing with many of the issues that turn up in the course of a design.

It would be quite different if we were teaching BSV over the course of a university term -- perhaps then we could even make understanding types a prerequisite, obtained from an earlier programming languages course. And there'd be time to go into all the details. But normally we don't have that luxury. That's why in the Reference Guide we want to reinforce the notion that a designer can do a whole lot after only the initial training, which is why we put the disclaimers there. But perhaps they could be worded a bit better -- we'll see what we can do.

Incidentally, Chris is correct about our type inspection facilities not dealing adequately with typeclasses and instances. This is something which is already on our enhancements list.

INVITATION

Chris and I have been having what seems to be a dialogue on this (and other topics). Can I invite others to join in? Tell us how we could do the training better; or what post-training resources would be useful. And maybe more pointers to explanations of some language features, not necessarily specific to BSV (such as the two Haskell Type Basics articles Chris pointed to).

TYPECLASSES

It remains the case, of course, that although you can do lots of good things after only the initial training, if you have had the chance to learn some of the advanced features you can do even more fantastic things. And, to come back to the detailed point Chris was making, it's true our documentation doesn't contain any examples of the sophisticated use of typeclasses. So, for interested readers, let me give a few examples.

(1) The DefaultValue package, in our release (see $BLUESPECDIR/BSVSource/Misc/DefaultValue.bsv). For examples of the use of this feature, also in the release, see the $BLUESPECDIR/BSVSource/Axi directory. AxiDefines.bsv contains declarations of some instances of DefaultValue, and AxiMaster.bsv some examples of their use.

(2) A more intricate example, the HList package, also in our release (see $BLUESPECDIR/BSVSource/misc/HList.bsv). This package is essentially transliterated from the equivalent package in the Haskell library, and "H" is for "heterogenous" -- it provides lists in which each element can be of a different type. So, since there are an infinite number of such list types, the set of them all has to be a typeclass. And since each of them has its own "head" and "tail" function types, they have to form typeclasses too. I'm afraid the package isn't very extensively commented -- but see what you make of it!

(3) The attached BuildVector package, which allows you to declare and initialize Vectors, in lines like
Vector#(5, UInt#(4)) = vec(7, 3, 8, 1, 11);
This is perhaps even more complicated, but it's very useful. You might ask why it isn't in our standard library. The answer is that, since it uses "advanced features", mistakes in its use might give rise to error messages which are unintelligible and therefore worrying to many of our users. In fact, I think that our typeclass error messages have improved since that decision was taken, so that we might revisit it. For example, if you get the number of elements different on the two sides of the definition, you still get an error message about provisos -- but now it ends with a strong hint as to what's gone wrong
(try it and see).

CONCLUSION

Finally, please don't hesitate to ask questions about any feature of BSV, advanced or otherwise, either on these forums or (if you prefer) to support@bluespec.com. If it prompts one of us (whether someone inside Bluespec or another user) to write a detailed reply, that might also have the extra value of becoming a draft of a new section of our documentation (subject of course to the permission of the author if non-Bluespec). The more traffic these forums see, the more useful they are!

Regards

joe stoy
Bluespec Inc.