Instance Allocation

Definition

GB_gameboy_t *GB_init(GB_gameboy_t *gb, GB_model_t model);
void GB_free(GB_gameboy_t *gb);

GB_gameboy_t *GB_alloc(void);
void GB_dealloc(GB_gameboy_t *gb);

bool GB_is_inited(GB_gameboy_t *gb);
size_t GB_allocation_size(void);

In gb.h

Description

These functions handle the creation and destruction of GB_gameboy_t instances that will emulate a specified model. There are three ways these functions can be used to create an instance:

1. Statically allocated:

static GB_gameboy_t gb;
GB_init(&gb, model);
/* ... */
GB_free(&gb);

This method can be used when you wish to avoid dynamic allocations. You must not use this method if you cannot guarantee the SameBoy headers you're compiling with are the exact same version as the SameBoy library you're linking against.

2. Dynamically allocated:

GB_gameboy_t *gb = GB_init(GB_alloc(), model);
/* ... */
/* GB_free(gb); */ // optional
GB_dealloc(gb);

GB_alloc will allocate a buffer with the right size for your instance, which can then be initialized with GB_init. GB_dealloc will call GB_free if it wasn't already called and free the allocated buffer. For convenience, GB_init always returns the first argument back.

3. Manually allocated:

GB_gameboy_t *gb = GB_init(my_custom_malloc(GB_allocation_size()), model);
/* ... */
GB_free(gb);
my_custom_free(gb);

Using GB_allocation_size, you can obtain the required buffer size for an instance, which can then be used to allocate a buffer for it using any arbitrary allocation method.

Additionally, GB_is_inited will return true if a GB_gameboy_t instance is initialized in a given buffer. If an instance is allocated in such a way before, it must be first freed with GB_free or GB_dealloc before being deallocated.

Thread Safety

GB_free and GB_dealloc must not be called if the instance is being run in any thread, including the current one (via a callback).

Notes

GB_init must not be called on an already initialized instance. You must first call GB_free on that instance to avoid memory leaks. If you merely want to switch to another emulated model, use GB_switch_model_and_reset.

See Also

• GB_gameboy_t
• GB_model_t
• GB_reset
• GB_switch_model_and_reset