4.0.0

Version 4.0.0 #

31 October 2021

Announcement #

We are excited to announce Fuel 4.0.0!

This version brings with it some changes that we have had in mind for years, as well as support for some of the newer features of Squeak, Pharo, and the OpenSmalltalk VM.

There’s still a lot to document so you will have to look at the code to get started. The public API methods on FLSerializer, FLMaterializer, and FLConfiguration include comments and FLUserGuidesTest and FLConfigurationTest show off some of the most interesting scenarios (you can load tests by loading the Tests Metacello group from the baseline). If you still have questions, please get in touch.

Unfortunately, none of us core developers use Fuel in their day jobs anymore. So it is possible that you will encounter issues, even though our test suite looks healthy. If you do, please open an issue on GitHub. We try to respond quickly.

I want to especially thank @noha and @seandenigris for pointing out that Fuel remains an important project and for pushing me to implement support for talents.

– @theseion, on behalf of the Fuel team

New Features #

Builder API #

For this version of Fuel we have rewritten much of the setup code to provide users with a builder API. Instead of having to instantiate different classes in a specific order, there are now only two classes that users really need to know about: FLSerializer and FLMaterializer. You can configure almost anything you need on these two classes and then send #serialize or #materializeRoot as the final message to kickstart Fuel. Here are two examples from the test suite:

objectToSerialize := Array
	with: 'hello'
	with: '' writeStream.

FLSerializer new
	when: [ :object | object isStream ] substituteBy: [ :o | nil ];
	object: objectToSerialize;
	fileName: 'demo.fuel';
	serialize.

materializedObject := FLMaterializer new
	fileName: 'demo.fuel';
	materializeRoot.

Object Limits #

For a long time we wanted Fuel to provide the option to limit the amount of objects that would be serialized. This does nothing for you if your goal is to serialize a complete object graph. But consider an application that serializes stack traces with Fuel. Depending on the application, the object graph could be very large, or there could easily be references that lead to serialization of the entire globals dictionary. In such a case you want to serialize as much of the relevant information as possible without assigning all of the processing resources to serialization. Keeping the application running is more important than serializing a stack trace.

We provide two different ways of limiting the object graph.

Total Objects Limit #

With FLSerializer>>limitObjectsTo: you set the maximum number of objects that Fuel will serialize. Think about the layout of your object graph before setting this option. Deep chains of references may cause parts of your graph to be lost that you want to keep. It is usually best to use this option in conjuntion with a depth limit. The primary reason for applying the total objects limit is to minimize the size of the resulting file and the amount of resources that go into serialization.

Depth Limit #

With FLSerializer>>limitDepthTo: you set the maximum distance from the root object that Fuel will serialize. This option is useful for trimming unnecessary information from your object graph, e.g. when serializing a stack trace.

Full Serialization Support By Default #

The Metalevel package is no more. Serialization of classes and methods is now part of the core package. There are a couple of advantages to this, one of the most interesting ones is that this makes it possible for us to support talents.

Class And Method Serialization For Squeak #

The Metalevel package has never, or at least not for a long time, worked in Squeak, which meant that Squeak users were limited to object instance graphs and global lookups. That’s fine for many cases but there are so many great things we can do with class and method serialization that it seems unfair to exclude Squeak users from the fun ;). Thanks to a more flexible approach to on-demand class compilation for tests that we implemented, it wasn’t too hard to get the tests running for Squeak and after a bit of work most of the things that work for Pharo also work for Squeak. There are some differences of course because of the differences in machinery but those will only matter in edge cases, in my opinion. At some point we will hopefully get around to documenting the differences, until then, don’t hesitate to get in touch.

Support For Talents And Anonymous Classes #

While working on support for talents we realized that we didn’t fully support anonymous classes (as the implementation of talents is based on anonymous classes). We now fully support anonymous classes and, therefore, talents.

Note that there are no anonymous classes, at least not officially. For our test suite we came up with a way to create anonymous classes so that our tests also succeed in Squeak. That means you can do some crazy things with Fuel and Squeak :).

Support For FullBlockClosure #

We now support FullBlockClosure for VM’s that use the Sista bytecodes. This is an exciting development because instances of FullBlockClosure can exist in isolation, decoupling them from their associated CompiledMethod.

Semantic Versioning #

The versioning in Fuel has always been an issue, especially the version check upon materialization. While the intentions were good, in practice we didn’t pay enough attention to what a version change meant semantically. For this release we’ve decided to finally fix that and adhere to semantic versioning. From this release on we will mark changes to serialization / materialization by incrementing the major version number. Small changes, e.g. API additions, or transparent optimizations, will be marked by incrementing the minor version number. Finally, small bug fixes and similar changes without direct impact will be marked by incrementing the patch version number.

In line with this change, the version check upon materialization will only raise a warning when the major version number differs. In addition, most exceptions raised by Fuel have been resumable since version 3.0.3, so you can still ignore it if you need to.

Removals #

We don’t have a lot of resources, so maintining parts of Fuel that go largely unused isn’t a good investment of our time. Often we’d also just ignore those parts when updating Fuel for new Pharo and Squeak versions, so many things outside of the core package have become outdated.

We have decided to remove the following packages:

  • FuelDebug
  • FuelPreview
  • FuelProgressUpdate

If you rely on any of these, please let us know.

Issue Cleanup #

We’ve closed many old issues on the GitHub issue tracker. Many of them have become obsolete or have already been addressed. Some are out of scope and, while interesting, don’t make much sense to keep around as open issues as long a no real interest in them exists. If there’s an issue that we closed that you think should be reopened, feel free to reopen it and leave a comment.

New Documentation Home #

You are probably reading this announcement on GitHub, the new home for the project documentation. We are still in the process of moving and updating old documentation so you will probably not find all the answers you’re looking for here. If you have a suggestion on how to improve the documentation, we welcome pull requests. Or open an issue and let us know.

Calendar Oct 31, 2021