Add New Example for Lifecycle Hooks Usage

[hendriknielaender]

Add New Example for Lifecycle Hooks Usage

Summary

While the recent addition of lifecycle hooks (beforeAll, afterAll, beforeEach, afterEach) to our benchmarking framework is a significant improvement, providing users with more control over their benchmarking environment, we currently lack comprehensive examples demonstrating how to effectively utilize these hooks. This issue proposes the creation of a new example that showcases the practical application of these lifecycle hooks.

Goals

• Enhance Documentation: Provide a clear, practical example that users can reference to understand how to implement and use lifecycle hooks in their benchmarks.
• Improve Usability: Help users quickly get started with lifecycle hooks, showcasing common use cases and best practices.

Proposed Example

The new example should cover:

• A simple benchmark scenario that requires setup and teardown operations.
• Use of beforeAll for global setup actions performed before any benchmarks run.
• Use of afterAll for global teardown actions performed after all benchmarks have completed.
• Use of beforeEach and afterEach for setup and teardown actions that need to be performed before and after each benchmark iteration, respectively.

Implementation Notes

• The example should be added to the /examples directory in the repository.
• Include comments in the example code to explain each part of the process and how the hooks are used.
• Consider creating a markdown document in the /docs directory that walks through the example in detail, providing additional context and explanation.

[AxelDelsol]

I tried to work on this issue by creating a variant of the bubble sort example. Instead of using a fixed array, the benchmark would generate a new one each iteration without being included in the measures.

The hook would be:

• before_all: initialize the array using an allocator and setup a random number generator
• before_each: fill the array with random values
• after_each: reset the array
• after_all: free the allocated memory

I ran into an issue when accessing the array and the random number generator. Since the hook functions do not accept any argument, I had to rely on global variables which is not ideal.

What are your thoughts about it ? A way to avoid global variable would be to initialize the hook with a *anyopaque passed around as in each function. But I do not have enough experience with Zig to graps the implications of having such public API for the end users.

[FObersteiner]

rely on global variables

just a quick thought on this; if you'd rely on an anyopaque pointer instead (have to trust that the recipient knows what to do with it), does this make things objectively better? I'm not a fan of globals either, but that doesn't mean that they don't have their uses (it depends...), and right now, I'm out of ideas for something better :)