DEV Community: Rory O'Connell

Fully encapsulating vulkan and win32 in mruby

Rory O'Connell — Wed, 10 Jun 2020 01:02:43 +0000

After about a week I finally finished pushing all of my original prototype work into the mruby VM. Previously the program was a C program which called into the mruby VM once per frame. Now it's the opposite, the C program does just enough to set up the VM state and then hand over control into the VM. For example, the main function originally looked like

int main() {
  ApplicationState *state = (ApplicationState *)VirtualAlloc(0, sizeof(ApplicationState), MEM_COMMIT, PAGE_READWRITE);

  state->ruby_state = mrb_open();
  create_GUI_class(state->ruby_state);

  load_ruby_files(state);
  mrb_sym world_sym = mrb_intern_cstr(state->ruby_state, "World");
  state->world_const = mrb_const_get(state->ruby_state,
                                     mrb_obj_value(state->ruby_state->object_class),
                                     world_sym);

  start_gui(state);
  loop(state);
  vkDeviceWaitIdle(state->vulkan_state.device);

  ImGui_ImplVulkan_Shutdown();
  ImGui_ImplWin32_Shutdown();
  ImGui::DestroyContext();

  CleanupVulkanWindow(state);
  CleanupVulkan(&state->vulkan_state);

  mrb_close(state->ruby_state);

  return 0;
}

The loop function was lengthy. Abbreviated, it looked like

void loop(ApplicationState *state) {
  MSG msg = {};

  while (msg.message != WM_QUIT) {
    ImGui_ImplVulkan_NewFrame();
    ImGui_ImplWin32_NewFrame();

    ImGui::NewFrame();
    int ai = mrb_gc_arena_save(state->ruby_state);
    mrb_funcall(state->ruby_state, state->world_const, "render", 0);
    mrb_gc_arena_restore(state->ruby_state, ai);
    ImGui::Render();
    FrameRender(state);
    FramePresent(state);
  }
}

This makes it more clear what I meant. The main program loop is C with the program state in an ApplicationState struct. It performed all of it's work in C, then yielded to the VM calling the Ruby code World.render, which I covered before. Control comes back to C where it finishes rendering the frame. This did work and I proved to myself the possibility of the idea I have in my mind. The switching of control back and forth between C and the VM caused stability issues. The wrong Ruby incantation causes the program crashing down.

There is also a secondary issue concerning me. I noticed that every frame the object count increased, causing a GC every few seconds.

This bothered me. From other experiences I understood calling back and forth between C and the VM could generate Proc objects. I was hoping that eliminating frequent calls to the VM would reduce or eliminate the amount of object garbage generated.

Now the main program looks like this

int main() {
  mrb_state *state = mrb_open();
  create_GUI_class(state);
  create_VulkanState_class(state);
  create_W32Window_class(state);
  create_Imgui_Impl_class(state);

  // we could do this within the VM now
  load_ruby_files(state);

  mrb_value World = mrb_obj_value(mrb_module_get(state, "World"));
  mrb_funcall(state, World, "start", 0);
  mrb_close(state);

  return 0;
}

The program does just enough to set up the VM and then passes control over to it. It creates four objects from C for interfacing with low level libraries like Vulkan and Win32.

The main entry point for the VM is in World.start

module World

def self.start
  @native_window = W32Window.new 'D E A R G', width: 1920, height: 1080
  # TODO see comments in VulkanState.cpp, need support for setting width/height
  # different from the native window eventually
  # shoutouts to wayland being massively different than every other
  # window system for no real good reason
  @vulkan_state = VulkanState.new @native_window
  ImguiImpl.startup @vulkan_state, @native_window

  while !@is_finished
    @native_window.process_window_messages
    ImguiImpl.new_frame
    process_windows
    ImguiImpl.render @vulkan_state
  end

rescue => ex
  puts "woah #{ex}"
  raise ex
ensure
  ImguiImpl.shutdown
end
end

This should now make it completely clear on what I mean by the program is now a Ruby program and not a C program. The main program loop runs Ruby methods. Some of the method implementations are in C. For example, the W32Window looks somewhat like the W32Window class I used as a research project. The VulkanState class is 500 lines of C performing all the Vulkan initialization ceremony. There's no need to cover that here, and I'm writing a book on Vulkan for that anyway! As an aside while going through the Vulkan implementation I discovered I was using chapters of my own book as reference over anything else I found. Good confidence boost that my authoring project is worthwhile.

We create module instance variables because native windows and Vulkan favor creating instances of data. We also place them in the World module as module instance variables so they aren't ever accidentally garbage collected. OpenGL has an internal hidden global state and wouldn't lend itself to this pattern. The same for imgui, it has an internal hidden state we interface with through C functions. That's why ImguiImpl is a global module with static methods.

Speaking of garbage collection I discovered an interesting and useful property of the mruby VM. When calling mrb_close(state), terminating the VM, the VM actually garbage collects all the remaining objects left in the VM! This gives us a chance for cleaning up the low level resources which I use for deallocating Vulkan objects. Similar to the old C++ RAII pattern. We can do this by declaring a custom deallocation function when registering the type with the VM. Usually we use the standard mrb_free

static const mrb_data_type VulkanState_type = { "VulkanState", VulkanState_delete };

Then we have an opportunity for destroying Vulkan objects correctly

void
VulkanState_delete(mrb_state* state, void* thing) {
  VulkanState* st = reinterpret_cast<VulkanState *>(thing);
  vkDeviceWaitIdle(st->device);
  // lots of vulkan yadda
  mrb_free(state, st);
}

Running it we have exactly the same result as before the move into the VM

Exactly the same, including the issue where it generates significant garbage every frame. That's a result I didn't expect since most of the execution happens within imgui and Vulkan C code. There's something else going on inside the VM I don't understand yet.

One other interesting note. Unlocking the frame rate and letting the system run as fast as possible results in a couple thousand FPS. Frame execution times are between 200 and 1000 nanoseconds, or 0.2 to 1.0 ms. This is without any optimizations, with garbage collection happening every few frames, and a debug binary. It encourages me that the speed of the VM won't become a hindrance later down the line. It also sticks in my mind that in the far future I'll need some threading systems separating the VM execution from the frame limit.

Next up I want to understand what all the object allocations are. The ObjectSpace and GC Ruby modules have some methods on interrogating the state of the VM memory and the statistics within. However, all of these methods perform a full GC on each method call. What I want are statistics on the metrics of the VM at that moment in time without any GC performed. That way I can perform historical analysis on the volume of objects generated and potentially where they came from. Since the entire project is within the VM building anything is a great deal faster and safer than previously. Interesting how a typical development cycle is the first tools you build on a new tool are tools to help you understand the tools you just built.

To build such tools I must have an understanding on how the mruby VM arranges and performs memory book keeping. That will be my next treatise, a full explanation on the mruby memory management system.

Receiving Data types as arugments with mruby

Rory O'Connell — Thu, 04 Jun 2020 22:50:20 +0000

It's funny when searching for examples on how to do something you end up getting results for posts you wrote a few days ago and not much else. I suppose that's a sign that I'm doing something bleeding edge and esoteric. Also props on dev.to for good SEO.

A quick hit for today, since apparently I not only accidentally started writing a book and accidentally started this mruby project, I also accidentally became the primary documenter for using mruby in practice. We learned how to create a Ruby class in C with mruby which stores arbitrary C data using the Data class type. What I want to do now is pass a Data instance as a parameter into another method. For example I'm pulling Win32 window management and Vulkan state into Ruby classes. Creating a VulkanState depends on a native window, in this case a Win32 window. The Ruby side is easy enough

@native_window = W32Window.new 'Foo', width: 1024, height: 768
@vulkan_state = VulkanState.new(@native_window)

Getting started with creating a VulkanState class is also typical

RClass *VulkanState_C = mrb_define_class(state, "VulkanState", state->object_class);
MRB_SET_INSTANCE_TT(VulkanState_C, MRB_TT_DATA);
mrb_define_method(state, VulkanState_C, "initialize",
                VulkanState_initialize, MRB_ARGS_REQ(1));

It's extracting the Data type with mrb_get_args which had me stumped for a while as I could not figure out how to get the right data type out. The documentation for mrb_get_args states how to get a Data type argument

| `d`  | data           | void *, {mrb_data_type} const | 2nd argument will be used to check data type so it won't be modified; when `!` follows, the value may be `nil` |

First try is a normal mrb_value

mrb_value
VulkanState_initialize(mrb_state* state, mrb_value self) {
  mrb_value gui_window;
  mrb_get_args(state, "d", &gui_window, &W32Window_data_type);

Which creates some wild looking data pointers in gui_window

Next attempt is try pulling the data out with DATA_PTR from the mrb_value

W32Window* window = reinterpret_cast<W32Window *>(DATA_PTR(gui_window));

Still wild data

Digging into the code, mrb_get_args automatically pulls out and type casts the void * for us using mrb_data_get_ptr. Therefore pulling a Data type out doesn't require any extra work from our side.

W32Window_data* gui_window;
mrb_get_args(state, "d", &gui_window, &W32Window_data_type);

Now it's correct

That's all! A complete abstract example on receiving a Data type as a method argument

struct Foo_data {
  uint32_t baz;
};

static const Foo_data_type = { "Foo", mrb_free };

mrb_value
Bar_get_foo(mrb_state* state, mrb_value* self) {
  Foo_data *foo_data;
  mrb_get_args(state, "d", &foo_data, &Foo_data_type);
  return mrb_nil_value();
}

RClass *Foo = mrb_define_class(state, "Foo", state->object_class);
MRB_SET_INSTANCE_TT(Foo, MRB_TT_DATA);
RClass *Bar = mrb_define_class(state, "Bar", state->object_class);
mrb_define_method(state, Bar, "get_foo", Bar_get_foo, MRB_ARGS_REQ(1));

Storing C data in an MRuby class

Rory O'Connell — Sat, 30 May 2020 04:35:30 +0000

Quick Friday hit for the 0 people following along my project and the dozen people discovering this years later from Google.

There aren't any good examples on creating a Ruby class with mruby that encapsulates data not used within the VM. This is something you need when you're using mruby to interface with a C library that provides it's own data types. You want to call methods in Ruby which run C code calling out to the external library. Examples include database systems, graphics APIs and interacting with the operating system.

It's a different though simpler process with mruby than mainline Ruby. C Ruby requires a separate allocate method before initialize. With mruby we can perform all operations with creating and storing C data all within the initialize method.

We'll use a contrived Foo_data struct.

struct Foo_data {
  uint32_t first[16];
  uint32_t second[16];
};

For demonstration we'll create a constructor for a Foo class taking one integer parameter. This parameter will instruct how to fill out the first and second members of a Foo_data struct that's a part of an instance of Foo. Building a Ruby Foo class in C like usual

mrb_state *state = mrb_open();
RClass *Foo = mrb_define_class(state, "Foo", state->object_class);
MRB_SET_INSTANCE_TT(Foo, MRB_TT_DATA);

mrb_define_method(state, Foo, "initialize", Foo_initialize, MRB_ARGS_REQ(1));
mrb_define_method(state, Foo, "check", Foo_check, MRB_ARGS_NONE());

There's a highly important new thing here. The MRB_SET_INSTANCE_TT sets the class object table type to the one specified. In this case we're setting this to a special MRB_TT_DATA. I neglected to do this step and encountered erratic difficult to debug program behavior. The program would follow pointers to nowhere and quit outright, not throwing the normal Access Violation error normally seen when following wild pointers.

Next we create a mrb_data_type. This is a struct which informs the mruby VM of the data type and the function to call when the GC comes for the object. It has two members, name and a function pointer. Name is a unique char* identifier, this is unique and identifies the data type. The name of the class, "Foo" is fine. The function pointer is what the GC calls when it destroys the object. If you're not doing anything special you can use the default built in function mrb_free

static const mrb_data_type Foo_type = {
  "Foo", mrb_free
};

Filling out the initialize method. We'll allocate a new Foo_data and save it to the instance on initialize.

mrb_value
Foo_initialize(mrb_state* state, mrb_value self) {
  mrb_int n;
  mrb_get_args(state, "i", &n);
  Foo_data *foo = (Foo_data *)DATA_PTR(self);
  if(foo) { mrb_free(state, foo); }
  mrb_data_init(self, nullptr, &Foo_type);
  foo = (Foo_data *)malloc(sizeof(Foo_data));

  for(uint32_t i = 0; i < 16; ++i) {
    foo->first[i] = i * n;
    foo->second[i] = i * n * n;
  }

  mrb_data_init(self, foo, &Foo_type);
  return self;
}

Explaining a couple things here. DATA_PTR pulls a void * out from the object specified, in this case self. We then cast it to what we want, a Foo_data *. For reasons I don't entirely understand, though recommended in this discussion and used in the mruby time gem we see if there already is a pointer associated with the instance. If so we free it.

We call mrb_data_init first to initialize the void * destined for holding the Foo_data *. Then a normal C heap allocation, and then filling out the data with the integer passed into the constructor. Calling mrb_data_init with the populated Foo_data * saves the data to the instance.

We extract it again at check

mrb_value
Foo_check(mrb_state* state, mrb_value self) {
  Foo_data *foo;
  Data_Get_Struct(state, self, &Foo_type, foo);
  mrb_assert(foo != nullptr);
  return mrb_nil_value();
}

Data_Get_Struct is a macro which will pull out and type cast the void * saved to the instance. All of the definitions and implementations are in data.h and data.c in the mruby code.

Now all that's left is create instances of Foo with different data and confirm with a debugger that the data is what we expect.

mrb_load_string(state, "a = Foo.new(10); a.check; b = Foo.new(50); b.check");

And that's it! It seems daunting at first understanding how to create a class within mruby for saving arbitrary C data with the lack of information. I hope this information makes the process clear and helps someone wanting to do the same.

The full program

#include <stdlib.h>
#include "mruby.h"
#include "ext\mruby\data.h"
#include "ext\mruby\class.h"
#include "ext\mruby\compile.h"

struct Foo_data {
  uint32_t first[16];
  uint32_t second[16];
};

static const mrb_data_type Foo_type = {
  "Foo", mrb_free
};

mrb_value
Foo_initialize(mrb_state* state, mrb_value self) {
  mrb_int n;
  mrb_get_args(state, "i", &n);
  Foo_data *foo = (Foo_data *)DATA_PTR(self);
  if(foo) { mrb_free(state, foo); }
  mrb_data_init(self, nullptr, &Foo_type);
  foo = (Foo_data *)malloc(sizeof(Foo_data));

  for(uint32_t i = 0; i < 16; ++i) {
    foo->first[i] = i * n;
    foo->second[i] = i * n * n;
  }

  mrb_data_init(self, foo, &Foo_type);
  return self;
}

mrb_value
Foo_check(mrb_state* state, mrb_value self) {
  Foo_data *foo;
  Data_Get_Struct(state, self, &Foo_type, foo);
  mrb_assert(foo != nullptr);
  return mrb_nil_value();
}

int main() {
  mrb_state *state = mrb_open();
  RClass *Foo = mrb_define_class(state, "Foo", state->object_class);
  MRB_SET_INSTANCE_TT(Foo, MRB_TT_DATA);

  mrb_define_method(state, Foo, "initialize", Foo_initialize, MRB_ARGS_REQ(1));
  mrb_define_method(state, Foo, "check", Foo_check, MRB_ARGS_NONE());

  mrb_load_string(state, "a = Foo.new(10); a.check; b = Foo.new(50); b.check");
  return 0;
}

Managing Windows Within mruby Part final: full encapsulation of state

Rory O'Connell — Fri, 29 May 2020 01:08:09 +0000

The color is mauve

One trivial realization I had regarding the bike shed. Before I had the pattern of naming C functions bound to Ruby methods like class_name_method_name_method. While this makes sense I think it's better naming the functions like ClassName_method_name instead. This make it more visually distinct and easier searching for it. I've changed to that naming scheme here.

Also a little debugging trick when loading code externally into the Ruby VM with functions like mrb_load_string. After the function call you can check for failure by checking if the VM has an unhandled exception, like so

mrb_load_string(mrb, "foo");
if(mrb->exc) {
mrb_print_error(mrb);
}

Now that I've established that the bike shed is mauve today, lets establish where we're at and what we're doing to finish off this exploratory code. Right now we have an instance of the mruby VM running and can create Windows windows calling into the VM. The Ruby methods implemented in C use the Win32 API to create new windows. These are remarkable achievements and we still have some polish left. We want everything possible within the VM. Enumerated, here's the steps we'll take

Change the create method to a constructor
Add add_window and remove_window class methods on W32Window. These keep track of the number of open windows. Set g_should_quit after the last window closes.
In the new W32Window constructor register itself to the open windows using the new W32Window.add_window method.
Perform a three step procedure registering arbitrary data with a Windows window. We'll assign the object_id of the W32Window instances to the Windows window. This is the most complicated part of the program
Change the callback function for processing Windows messages to call W32Window.remove_window when the window closes. When there are no more windows left, the callback function requests the program quits.

Creating a constructor method in C with mruby

This is straightforward. Just as if we're working entirely within Ruby we define an initialize instance method which the VM calls when we call new. Lets rename the original w32_window_create_method to W32Window_initialize and change mrb_define_class_method to mrb_define_method appropriately

RClass *W32Window = mrb_define_class(mrb, "W32Window", mrb->object_class);
mrb_define_method(mrb, W32Window, "initialize",
                        W32Window_initialize, MRB_ARGS_REQ(2));

Then change mrb_load_string to create an instance instead of calling create

mrb_load_string(mrb, "5.times { |n| W32Window.new \"Window #{n}\", width: n * 100, height: n * 100 }");
if(mrb->exc) {
  mrb_print_error(mrb);
}

Running this works exactly as before. The difference is we now have an instance backing each window. This allows us in the near future to match a Windows window with a Ruby object instance later.

The function prototypes for instance variable manipulation are in the variable.h header. Add that include at the top of the file. We're using the mrb_iv_set function, which is the equivalent of instance_variable_set :@foo, 'bar'. It's definition

mrb_iv_set(mrb_state *mrb, mrb_value obj, mrb_sym sym, mrb_value v)

The only new thing here is the mrb_sym type. It's actually a typedef of uint32_t. Every symbol in Ruby is an index to a global hashed symbol table. The integer value is there result of the hash.

There are handy C functions for creating and finding symbols. The easiest one for our case is mrb_intern_cstr. The documentation implies that it creates a symbol. This function actually finds an existing symbol based upon the C string provided or creates a new symbol in the VM and returns a new symbol.

Putting it all together, right after extracting the arguments

mrb_iv_set(state, self, mrb_intern_cstr(state, "@window_name"), window_name);

Lets validate that this works by changing up the mrb_load_string line a bit

mrb_load_string(mrb, "1.upto 5 { |n| puts W32Window.new(\"Window #{n}\", width: n * 100, height: n * 100).inspect }");

One special thing about creating an instance. Currently we are returning mrb_nil_value(). While this is currently working the new method actually returns nil instead of the new instance. Change return mrb_nil_value() to return self.

Populating a Win32 window with a Ruby Object ID

Now we create instances of objects in the VM for each Win32 window we create. There is a disconnect between our instance and the window callback function. When Windows send a message to our window our callback function main_window_callback runs with the message passed into it. What we don't know is which Ruby object that window belongs to. We do know the HWND of that window. With that we could create a table in the VM of HWND objects to W32Window instances. However we have a shorter path available. Windows supports passing an arbitrary pointer upon creating the window. You can also set an arbitrary pointer on the window after it's finished creating. Microsoft has a detailed article explaining the procedure.

Notice the important distinction. CreateWindowEx initiates the window creation. We can pass an arbitrary pointer to CreateWindowEx as the last parameter, but we cannot set the arbitrary pointer on the window yet. For that, when Windows finishes constructing the window and just before presenting it, it sends the window the WM_CREATE message, with the LPARAM in the callback function set as the pointer we specified in CreateWindowEx. This means setting a pointer to our Ruby object on the window is a two step process. First, get the C pointer to self and pass it as the last parameter to CreateWindowEx. Then, in our callback function, intercept the WM_CREATE message. Cast the LPARAM back to the Ruby pointer, then use SetWindowLongPtr to store the pointer along with the window so we can get it back later.

This is the gnarliest bit of code we'll ever get into so I want to be sure we're all understanding the different components involved. We cannot have full control over the window and events, Windows controls that. Windows notifies us when things happen through sending messages to our callback function. Our task is matching up the window messages with data inside the VM. In particular we want the VM to maintain a list of the open windows. When the list is empty, we want to notify Windows to terminate the program. Each time we create a window within the VM we add to the list. When Windows notifies us it destroyed a window we remove it from our list.

When Windows calls our callback function we're in the C. What we need now is a pattern in C for locating objects in the VM from outside the VM. The first intuition is get a C pointer to the live objects inside the VM. It's not recommended we keep a C pointer to VM objects. That pointer can become invalid for reasons outside our control resulting in a hard crash following a wild pointer. The object it points to can get garbage collected if we're not careful. The VM may move data around in memory, like the Ruby 2.7 heap compacting feature. What we do have that's guaranteed stable and unique for identifying objects within the VM is the object_id of every object. We'll use the object_id, a 64 bit unsigned integer.

Keeping track of all open windows within Ruby

To get started lets add a bit of Ruby code. We'll have the W32Window class keep track of all of it's instances.

RClass *W32Window = mrb_define_class(mrb, "W32Window", mrb->object_class);
const char* ruby_str = R"(
class W32Window
  @open_windows = []

  def self.add_window obj
    @open_windows.push obj
  end

  def self.remove_window oid
    @open_windows.delete_if { |e| e.object_id == oid }
  end
end)";
mrb_load_string(mrb, ruby_str);

This sets us up for success later. Although iterating using Ruby code isn't as efficient as writing it in C this isn't called on a hot path.

In the W32Window_initialize function, lets add to the @open_windows upon creation using the method. We can call methods on Ruby objects from C using mrb_funcall.

mrb_value mrb_funcall(mrb_state *mrb, mrb_value val, const char *name, mrb_int argc, ...);

This is equivalent to obj.send :method_name, arg1, arg2 .. ,argN. The second parameter is the object we're sending the message to, third is a const char * of the name of the method, fourth is the number of method arguments we're sending, and then the va_args of the mrb_values as method parameters.

mrb_funcall(state, mrb_obj_value(mrb_obj_ptr(self)->c),
            "add_window", 1, self);

(There is a slightly more type-safe way using mrb_funcall_argv which takes an mrb_symbol for the method name instead of a literal C string)

The strange bit is mrb_obj_value(mrb_obj_ptr(self)->c). What we're doing here is the Ruby equivalent of self.class.add_window self. The construction mrb_obj_value(mrb_obj_ptr()) is like self.class. mrb_obj_ptr is a macro which takes any mrb_value type and casts it's void * value.p to an RObject *. (Recall that every mrb_value is a wrapper with a void *, and the tt member of the mrb_value informs how to interpret the void * With an RObject * we can get the objects RClass * by following the ->c pointer. However, mrb_funcall doesn't want an RClass * or RObject *, it wants an mrb_value. So we have to convert the RClass * back to an mrb_value using the mrb_obj_value function.

Next we need a pointer to a bundle of data that we'll store with the window that we get back when Windows sends the window messages. We need two things, the mrb_state and the object_id of the W32Window instance tied to that window. Lets add that just underneath all the #includes

struct W32Window_cb_data {
  mrb_state* state;
  uint64_t object_id;
};

And then allocate a bit of memory on the heap to contain the data. I 100% would rather not allocate memory for such a situation. I did commit to working in Rome by working with a dynamic language with lots of small heap memory allocations, and will therefore work as the Romans do.

W32Window_cb_data *cb_data = reinterpret_cast<W32Window_cb_data *>
(malloc(sizeof(W32Window_cb_data)));
cb_data->state = state;
cb_data->object_id = mrb_obj_id(self);

Now finally pass that along to CreateWindowEx as the last parameter.

HWND main_window = CreateWindowEx(0, wclass.lpszClassName, RSTRING_PTR(window_name),
                                  main_window_style, CW_USEDEFAULT, CW_USEDEFAULT,
                                  mrb_fixnum(kw_values[0]),
                                  mrb_fixnum(kw_values[1]),
                                  0, 0,
                                  GetModuleHandle(nullptr),
                                  cb_data);

Attaching the Ruby Object ID to the window

Great, that's the first part done. We allocated the information we need later and passed it along to the next step. The next step is extracting the pointer and saving it to the window's user data when Windows sends our window the WM_CREATE message. At the top of the main_window_callback we'll do that using SetWindowLongPtr

if(message == WM_CREATE) {
  CREATESTRUCT* create = reinterpret_cast<CREATESTRUCT *>(lparam);
  LONG_PTR objectid_ptr = reinterpret_cast<LONG_PTR>(create->lpCreateParams);
  SetWindowLongPtr(window, GWLP_USERDATA, objectid_ptr);
}

When windows sends the WM_CREATE messages it populates the lparam as a CREATESTRUCT. That type encapsulates all the parameters passed into CreateWindowEx. The member of the CREATESTRUCT we care about is lpCreateParams. That's the W32Window_cb_data we passed in into CreateWindowEx. We relay it one last time, setting the GWLP_USERDATA pointer to the W32Window_cb_data window pointer. We won't return after this condition, we'll let the rest of the function continue as normal.

Deleting a Ruby object on window close

Now one last bit. We'll catch message sent to our window when Windows deletes the window. This is the WM_DESTROY message. What we'll do is extract the GWLP_USERDATA pointer from the closing window, cast it back to the W32Window_cb_data pointer, call W32Window.remove_window with the object_id. Then we'll check if there are less than 1 open windows. If so, we'll tell Windows to terminate the program just as before with PostQuitMessage. Since we used malloc to create a small struct on the heap containing W32Window_cb_data, we also have to free it to avoid a memory leak. The whole procedure in code, replacing WM_CLOSE with WM_DESTROY. There isn't anything here we haven't seen previously.

case(WM_DESTROY): {
  LONG_PTR instance_pointer = GetWindowLongPtr(window, GWLP_USERDATA);
  W32Window_cb_data *cb_data = reinterpret_cast<W32Window_cb_data*>(instance_pointer);
  RClass *klass = mrb_class_get(cb_data->state, "W32Window");
  assert(klass != nullptr);

  mrb_value oid;
  SET_INT_VALUE(oid, cb_data->object_id);
  mrb_funcall(cb_data->state, mrb_obj_value(klass), "remove_window", 1, oid);

  mrb_value open_windows = mrb_obj_iv_get(cb_data->state,
                                          (RObject *)klass,
                                          mrb_intern_cstr(cb_data->state, "@open_windows"));
  if(RARRAY_LEN(open_windows) < 1) {
    PostQuitMessage(0);
  }

  free(cb_data);
  break;
}

Compiling and running now, it works as expected! The program continues running until all the windows close.

This is a pretty large achievement. We integrated with Win32 while pushing most of the state of the program into the Ruby VM. Most of it. There's one last thing left, the main program loop is still in C. Lets put that into Ruby as well.

Moving the main program loop to Ruby

Lets create an Application module with four static methods on it start, loop, quitand process_windows_messages. The first three are basic Ruby methods. The last one is a method we'll implement in C. We'll push our current mrb_load_string call creating W32Windows into start, call process_windows_messages in the loop, and then set a flag when we call quit that the program should terminate.

First create the Application module in C so we have an easy reference to it later.

RClass *Application = mrb_define_module(mrb, "Application");

Adding to the current ruby_str string.

module Application
  @is_running = true

  def self.start
    1.upto 5 do |n|
      W32Window.new("Window #{n}", width: n * 100, height: n * 100)
    end
    loop
  end;

  def self.loop
    while @is_running
      process_windows_messages
    end
  end

  def self.quit
    @is_running = false
  end
end

Define the Application.process_windows_messages in C, moving the while(PeekMessage) loop into it. When we receive the WM_QUIT message, we call the Application.quit method instead of setting g_should_quit instead.

mrb_value
Application_process_windows_messages(mrb_state* state, mrb_value self) {
  MSG message = {};
  while(PeekMessage(&message, nullptr, 0, 0, PM_REMOVE)) {
    switch (message.message) {
    case (WM_QUIT): {
      mrb_funcall(state, self, "quit", 0);
      break;
    }
    default: {
      TranslateMessage(&message);
      DispatchMessage(&message);
      break;
    }
    }
  }
  return mrb_nil_value();
}

Then add the process_windows_messages method on Application using mrb_define_module_function

mrb_define_module_function(mrb, Application, "process_windows_messages",
                            Application_process_windows_messages, MRB_ARGS_NONE());

Now we can delete the original loop and g_should_quit as these are entirely within the Ruby VM state.

The last thing we have to do is call start on Application to kick off the program loop written entirely in Ruby

mrb_funcall(mrb, mrb_obj_value(Application), "start", 0);

Compile and run again, it still works exactly as before. However, the amazing thing here is now the VM controls absolutely everything about the program. All of the program's functionality sets up the VM state and then kicks off the VM in a program loop. We implement Ruby methods in C whenever we must interface with something external to the VM. It's memory stable, though in it's current state it dominates the CPU. It runs the program loop as fast as possible. A quick though inelegant fix is add the mruby-sleep gem in the build_config.rb and rebuild mruby. This provides a sleep method for throttling the while loop.

More polish

While this all works and we could wrap up our exploratory program there's one last little thing that bothers me. We call RegisterClassEx with the same information and window class name. While this doesn't crash the program it is an error. Lets fix this little error so that we create one window class on program start and use that instead.

Lets create a W32Window.register_window_class and call it within Application.start. We'll use the class name of W32Window as the Windows window class name. Move all of the code regarding registering a Windows window class into it.

mrb_value
W32Window_register_window_class(mrb_state *state, mrb_value self) {
  mrb_value klass_name = mrb_class_path(state, mrb_class_ptr(self));
  WNDCLASSEX wclass = {};
  wclass.cbSize = sizeof(WNDCLASSEX);
  wclass.lpszClassName = RSTRING_PTR(klass_name);
  wclass.lpfnWndProc = main_window_callback;
  wclass.hInstance = GetModuleHandle(nullptr);
  wclass.style = CS_OWNDC | CS_VREDRAW | CS_HREDRAW;
  RegisterClassEx(&wclass);

  return mrb_nil_value();
}

Only thing new here is mrb_class_path which returns an mrb_value containing the string name of the class. It's the same as calling W32Window.name within Ruby. Register this as a class method

mrb_define_class_method(mrb, W32Window, "register_window_class",
                        W32Window_register_window_class, MRB_ARGS_NONE());

Then within W32Window_initialize use the Ruby class name for registering the Windows window class

mrb_value klass_name = mrb_class_path(state, mrb_class(state, self));

CreateWindowEx(0, RSTRING_PTR(klass_name), RSTRING_PTR(window_name),

Lastly call W32Window.register_window_class at the top of the Application.start method. Compile and run and it works exactly as before, the only difference here is that it's more 'correct' as we're not repeatedly creating the same window class every time we create a new window.

The end of a mini series

That's it for this exploratory code. I've proved to myself that it is possible encapsulating state entirely within the Ruby VM while working with a complicated external system in C. The size of the program by line count doubled. There is an increased mental overhead of passing data back and forth out to Windows and receiving it back in the message callback.

There are other approaches to this. We could keep some state in C like we did previously or keep tables of mapping from C to the Ruby VM in C and translate them ourselves when we need. Those approaches is how the current Ruby integrated environment I'm working on currently functions. I run into issues with this approach, where the right Ruby incantation can bring the whole program down in a hard to debug fashion. I've found that keeping as much within the Ruby VM as possible dramatically decreases complexity and increases the amount of debugging tools available especially as I add more functionality to the environment.

Two things I did not get a chance to touch on are mrb_data types, which allow you to set instance variables wrapping C structures, and the MRB_TT_CPTR class type encapsulating a C pointer.

I'm now taking the techniques I learned here and bringing them back to my still unnamed project. It will take a while encapsulating it's current state into Ruby fully. A lot of uninteresting error prone grunt work not worth documenting.

The entire final exploratory program

#include <windows.h>
#include <stdio.h>
#include <assert.h>
#include "mruby.h"
#include "mruby/compile.h"
#include "mruby/string.h"
#include "mruby/variable.h"
#include "mruby/array.h"
#include "mruby/class.h"

struct W32Window_cb_data {
  mrb_state* state;
  uint64_t object_id;
};

LRESULT CALLBACK
main_window_callback(HWND window, UINT message, WPARAM wparam, LPARAM lparam) {
  if(message == WM_CREATE) {
    CREATESTRUCT* create = reinterpret_cast<CREATESTRUCT *>(lparam);
    LONG_PTR objectid_ptr = reinterpret_cast<LONG_PTR>(create->lpCreateParams);
    SetWindowLongPtr(window, GWLP_USERDATA, objectid_ptr);
  }

  LRESULT result = 0;
  switch(message) {
  case(WM_DESTROY): {
    LONG_PTR instance_pointer = GetWindowLongPtr(window, GWLP_USERDATA);
    W32Window_cb_data *cb_data = reinterpret_cast<W32Window_cb_data*>(instance_pointer);
    RClass *klass = mrb_class_get(cb_data->state, "W32Window");
    assert(klass != nullptr);

    mrb_value oid;
    SET_INT_VALUE(oid, cb_data->object_id);
    mrb_funcall(cb_data->state, mrb_obj_value(klass), "remove_window", 1, oid);

    mrb_value open_windows = mrb_obj_iv_get(cb_data->state,
                                            (RObject *)klass,
                                            mrb_intern_cstr(cb_data->state, "@open_windows"));
    if(RARRAY_LEN(open_windows) < 1) {
      PostQuitMessage(0);
    }

    free(cb_data);
    break;
  }
  default: {
    result = DefWindowProc(window, message, wparam, lparam);
  }
  }
  return result;
}

mrb_value
W32Window_register_window_class(mrb_state *state, mrb_value self) {
  mrb_value klass_name = mrb_class_path(state, mrb_class_ptr(self));
  WNDCLASSEX wclass = {};
  wclass.cbSize = sizeof(WNDCLASSEX);
  wclass.lpszClassName = RSTRING_PTR(klass_name);
  wclass.lpfnWndProc = main_window_callback;
  wclass.hInstance = GetModuleHandle(nullptr);
  wclass.style = CS_OWNDC | CS_VREDRAW | CS_HREDRAW;
  RegisterClassEx(&wclass);

  return mrb_nil_value();
}

mrb_value
W32Window_initialize(mrb_state* state, mrb_value self) {
  mrb_value window_name;
  mrb_int width;
  mrb_int height;
  const char* kw_names[2] = { "width", "height" };
  mrb_value kw_values[2] = {};
  const mrb_kwargs kwargs = { 2, kw_values, kw_names, 2, nullptr };
  mrb_get_args(state, "S:", &window_name, &kwargs);
  mrb_funcall(state, mrb_obj_value(mrb_obj_ptr(self)->c),
              "add_window", 1, self);
  mrb_iv_set(state, self, mrb_intern_cstr(state, "@window_name"), window_name);

  DWORD main_window_style = (WS_OVERLAPPEDWINDOW | WS_VISIBLE);

  W32Window_cb_data *cb_data = reinterpret_cast<W32Window_cb_data *>(malloc(sizeof(W32Window_cb_data)));
  cb_data->state = state;
  cb_data->object_id = mrb_obj_id(self);

  mrb_value klass_name = mrb_class_path(state, mrb_class(state, self));

  CreateWindowEx(0, RSTRING_PTR(klass_name), RSTRING_PTR(window_name),
                 main_window_style, CW_USEDEFAULT, CW_USEDEFAULT,
                 mrb_fixnum(kw_values[0]),
                 mrb_fixnum(kw_values[1]),
                 0, 0,
                 GetModuleHandle(nullptr),
                 cb_data);

  return self;
}

mrb_value
Application_process_windows_messages(mrb_state* state, mrb_value self) {
  MSG message = {};
  while(PeekMessage(&message, nullptr, 0, 0, PM_REMOVE)) {
    switch (message.message) {
    case (WM_QUIT): {
      mrb_funcall(state, self, "quit", 0);
      break;
    }
    default: {
      TranslateMessage(&message);
      DispatchMessage(&message);
      break;
    }
    }
  }

  return mrb_nil_value();
}

int main() {
  mrb_state *mrb = mrb_open();
  RClass *W32Window = mrb_define_class(mrb, "W32Window", mrb->object_class);
  RClass *Application = mrb_define_module(mrb, "Application");

  const char* ruby_str = R"(
class W32Window
  @open_windows = []

  def self.add_window obj
    @open_windows.push obj
  end

  def self.remove_window oid
    @open_windows.delete_if { |e| e.object_id == oid }
  end
end

module Application
  @is_running = true

  def self.start
    W32Window.register_window_class

    1.upto 5 do |n|
      W32Window.new("Window #{n}", width: n * 100, height: n * 100)
    end

    loop
  end;

  def self.loop
    while @is_running
      process_windows_messages
    end
  end

  def self.quit
    @is_running = false
  end
end
)";

  mrb_load_string(mrb, ruby_str);

  mrb_define_class_method(mrb, W32Window, "register_window_class",
                          W32Window_register_window_class, MRB_ARGS_NONE());

  mrb_define_method(mrb, W32Window, "initialize",
                    W32Window_initialize, MRB_ARGS_REQ(2));

  mrb_define_module_function(mrb, Application, "process_windows_messages",
                             Application_process_windows_messages, MRB_ARGS_NONE());

  mrb_funcall(mrb, mrb_obj_value(Application), "start", 0);

  mrb_close(mrb);

  return 0;
}

Managing Windows windows within mruby Part 2: Creating a window from mruby

Rory O'Connell — Mon, 25 May 2020 02:36:08 +0000

We'll build off of the previous program where we created a Windows window using the Win32 API. Now we're adding the mruby VM to our program and then push creation of the Win32 window into the VM instead of calling it from our main() function.

First we need to build mruby. This is a simple affair. There is a bit of a catch-22 as the automated build scripts are in Ruby. While Ruby used to be a pain on Windows it's simple today. Easiest is through chocolatey and install the Ruby package with choco install ruby. That's it!

Clone the mruby repo and check out latest tag, currently 2.1.0, or download the latest release and extract.

mruby / mruby

Lightweight Ruby

What is mruby

mruby is the lightweight implementation of the Ruby language complying to (part of) the ISO standard. Its syntax is Ruby 2.x compatible.

mruby can be linked and embedded within your application. We provide the interpreter program "mruby" and the interactive mruby shell "mirb" as examples You can also compile Ruby programs into compiled byte code using the mruby compiler "mrbc". All those tools reside in the "bin" directory. "mrbc" is also able to generate compiled byte code in a C source file, see the "mrbtest" program under the "test" directory for an example.

This achievement was sponsored by the Regional Innovation Creation R&D Programs of the Ministry of Economy, Trade and Industry of Japan.

How to get mruby

The stable version 2.1.0 of mruby can be downloaded via the following URL: https://github.com/mruby/mruby/archive/2.1.0.zip

The latest development version of mruby can be downloaded via the following URL: https://github.com/mruby/mruby/zipball/master

…

View on GitHub

Run ruby minirake from dir. There are some warnings about macro re-definitions, they're harmless. When finished, copy build\host\*.lib to the win32 project dir. Copy recursive include to the project dir as well.

Either modify the batch file, adding /Imruby to compile options, or modify the .h files to use relative paths "" instead of <> include paths. Either works, I prefer the latter.

Within the batch file, add libmruby.lib libmruby_core.lib to the end of the line, telling the linker to use the mruby libraries for external symbols.

Now we'll test mruby. Add #include "mruby.h" to the top of the cpp file. At the top of main add mrb_state *mrb = mrb_open();. Bottom add mrb_close(mrb). Compile and run, ensuring everything is fine.

Important!

Before we go on there are two fundamental things required to understand. The entire VM state is in the mrb_state type we just created. We pass that state as the first parameter to all mruby functions. This is a common C pattern seen lately. Older C programs and libraries used a pattern of global hidden state. Examples include the main Ruby C interface and famously OpenGL. Now it's more common for C programs using a pointer to an internal state instead. This adds a great deal more flexibility at the cost of a bit more verbose syntax.

The other fundamental piece of information is everything with mruby uses an mrb_value type. It's similar to the C Ruby VALUE type.

union mrb_value_union {
  mrb_float f;
  void *p;
  mrb_int i;
  mrb_sym sym;
};
typedef struct mrb_value {
  union mrb_value_union value;
  enum mrb_vtype tt;
} mrb_value;

The mrb_vtype tt is important here. That specifies the table type of this value and informs how to access it. For float, fixnums, and symbol table types use the f, i and sym members of the union respectively. All others use the void *p type, with the tt property informing how to interpret the void *. For example if we have an mrb_value with a tt of MRB_TT_CLASS we cast the p member of the union to an RClass *.

// or use reinterpret_cast<RClass *> if you like more explicit C++ casts
RClass *klass = (RClass *)foo.value.p;

Sometimes you see the API use or return types like mrb_string or mrb_int. These ultimately come from a source mrb_value. If you're debugging trying to figure out why you're getting information you don't expect, back up the stack until you find the source mrb_value these derived types come from.

Much of the mruby API looks like the main Ruby C API. The Ruby C API is well covered at this point. If you're looking for information on how to do something and the information for mruby isn't readily available you can find examples with the Ruby C API and translate it back. Beyond that reading the mruby header files, mruby C source implementation, and looking at the implementation of mruby gems provides insight. All of the C code with mruby and gems surrounding it is easy to read. There are no C tricks or hard to parse syntax. Oftentimes reading the C implementation is close to reading Ruby code with some extra steps.

Creating objects in the mruby vm

First thing we'll do is create a new class in the ruby VM. This is the same as class W32Window; end;. We can do this with mrb_define_class. After initializing the mruby state, add

// RClass *mrb_define_class(mrb_state *mrb, const char *name, struct RClass *super);
RClass *window_manager_class = mrb_define_class(mrb, "W32Window", mrb->object_class);

mruby automatically creates the base object when we initialize the mrb_state and places a reference in the object_class pointer in the state. Remember, everything in Ruby comes from Object eventually, even classes, so we set the third parameter to the root object to inherit from.

Right now we'll treat W32Window as a static object containing all of it's state. We could use W32Window as a module instead. If we were to do that we'd use mrb_define_module(mrb, "W32Window");, which corresponds to module W32Window; end;. Either works for now, though I'm using a class since I'll refactor it into a constructor later.

Now that we have an RClass * we can use C to define methods in it. Defining class which runs C code instead of Ruby code is a two step process. One, define a function in C which runs when we call the Ruby method. Two, define a method on a Ruby object pointing to the C function. Lets create a test method named foo on the W32Window class which prints something to standard out. We'll be doing the Ruby equivalent of

class W32Window
  def self.foo
    puts "Hello from W32Window.foo"
  end
end

Bound mruby methods have a signature mrb_value function_name(mrb_state *state, mrb_value self). I prefer naming bound C functions with a naming pattern of class_name_method_name_method. In this case we'll name the C method w32_window_foo_method means W32Window.foo. Filling it all out we have the function

mrb_value
w32_window_foo_method(mrb_state* state, mrb_value self) {
  printf("Hello from W32Window.foo\n");
  return mrb_nil_value();
}

Every Ruby method must return some value so we'll return nil, of which there's a helpful function for.

Now the last step is creating the method on an object. For a class method this is mrb_define_class_method. For a method on a module, it is mrb_define_module_function. And a normal instance method, mrb_define_method. All have a similar signature. We're defining a class method on W32Window.

// void mrb_define_class_method(mrb_state *mrb, struct RClass *cla, 
//                              const char *name, mrb_func_t fun, 
//                              mrb_aspec aspec);
mrb_define_class_method(mrb, window_manager_class, "foo",
                        w32_window_foo_method, MRB_ARGS_NONE());

Which is all straightforward. The last parameter differs from the mainline Ruby rb_define_method. mruby uses an mrb_aspec type. This defines bit patterns for specifying the number and kind of arguments, while Ruby uses an integer with extended parameters. There are helpful macros for creating the right bit pattern, such as MRB_ARGS_NONE(). You can read the mruby.h header for all the macros for specifying number and types of parameters for a C function called from Ruby.

That's really all there is to it. We can test it out by calling the C function mrb_load_string, which is like an eval from the C side. This function is fine for limited testing or one off execution. You should not use it repeatedly in code paths since it performs a parse, compilation and execution every time. It's function prototype lives in the compile.h, so #include "mruby/compile.h" first and then

mrb_load_string(mrb, "W32Window.foo");

If you're working off of the previous Win32 project, place this function call after the CreateWindowEx call. Windows does not set up stdout until after window creation. Build, run and you'll see Hello from W32Window.foo in the console just as you expect.

Lets take a step back and analyze what we just put together. We created a new mruby VM state with mrb_open. Then, using C functions, created a new class within the Ruby VM called W32Window. We added a class method named foo on the new W32Window class. That class method runs the C function window_manager_foo_method instead of running Ruby code. Within that C function we print a message to standard out. Finally, we execute some Ruby code within the VM with C.

Creating a Win32 window within mruby

Now you see the back and forth between a C program and the mruby VM. What we want to do is push everything we can into the mruby VM. Lets do the simplest thing possible by pushing the Win32 window creating into a C function called by the VM instead. This is still fragile and has issues though it's a good first step.

Delete everything related to creating the foo method on W32Window. We'll add a create class method on the class which does all the win32 calls instead. We'll move all the Win32 window creation code into this function. It's a simple enough procedure, simply showing some of the code is sufficient for understanding. It's not much different than we already did with our test function with printf

mrb_value
w32_window_create_method(mrb_state* state, mrb_value self) {
  WNDCLASSEX wclass = {};
  wclass.cbSize = sizeof(WNDCLASSEX);
  wclass.lpszClassName = "mainWindowClass";
  wclass.lpfnWndProc = main_window_callback;
  wclass.hInstance = GetModuleHandle(nullptr);
  wclass.style = CS_OWNDC | CS_VREDRAW | CS_HREDRAW;
  RegisterClassEx(&wclass);

  DWORD main_window_style = (WS_OVERLAPPEDWINDOW | WS_VISIBLE);

  HWND main_window = CreateWindowEx(0, wclass.lpszClassName, "Playground",
                                    main_window_style, CW_USEDEFAULT, CW_USEDEFAULT,
                                    1024, 768,
                                    0, 0, GetModuleHandle(nullptr), 0);

  return mrb_nil_value();
}

/// before the main loop
mrb_define_class_method(mrb, w32_window_class, "create",
                        w32_window_create_method, MRB_ARGS_NONE());

mrb_load_string(mrb, "W32Window.create");

Run this program and... it's exactly the same as before. Which in this case is a good thing! There's a profound difference in the execution path. Now when we create a Win32 window we are within the context of the mruby VM and all it provides us. Lets do a simple proof of that. Change the mrb_load_string to

mrb_load_string(mrb, "5.times { W32Window.create }");

Running this program we now see we have five identically behaving Win32 windows!

They all behave identically in that closing any one of them quits the program. Initially we assumed we would have only one window. In our callback function when we receive a WM_CLOSE message, which happens when the window closes, we quit the program using PostQuitMessage. We want to keep track of all the open windows and then quit when the last window closes. We'll get to that next time when we start encapsulating C data into an mruby class. For now slap a //TODO in the code and lets move on.

Extracting mruby parameters in C

Lets make our creation a bit more interesting. Lets make the create method take parameters for the window title and dimensions. Written in Ruby, the method would look like def self.create window_title, width: 1024, height: 768. Starting with window_title first, we have to change the mrb_define_class_method declaring that we have one required parameter. Change MRB_ARGS_NONE to MRB_ARGS_REQ(1). The Ruby VM enforces one method argument now.

It's a simple process extracting Ruby method arguments in a method implemented in C. We use the mrb_get_args function for extracting copies of the arguments into mrb_value types. The first parameter is an mruby_state, second is a format specifier, and the rest are va_args matching the format specifier. Right from the mruby header file

/**
 * Retrieve arguments from mrb_state.
 *
 * @param mrb The current MRuby state.
 * @param format is a list of format specifiers
 * @param ... The passing variadic arguments must be a pointer of retrieving type.
 * @return the number of arguments retrieved.
 * @see mrb_args_format
 * @see mrb_kwargs
 */
MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);

The format specifier specifies the type of argument passed in to what position. It's a standard c-string similar to printf. Since currently we're expecting a string for the window title we use the format specifier "S". Lastly we pass a reference to an empty mrb_value that mrb_get_args populates. See the mruby.h header file detailing the format specifier arguments. At the top of w32_window_create_method

mrb_value window_name;
mrb_get_args(state, "S", &window_name);

Now all we need to do is use the passed parameter as the window title instead of the hardcoded string "Playground". Note that we have an mrb_value instead of a char *. There are helpful macros for extracting data out of mrb_value types to C types. First we need to #include "mruby/string.h" for their definitions. Then we can replace "Playground" with RSTRING_PTR(window_name).

Change our call in mrb_load_string to something more interesting that demonstrates our new capabilities.

mrb_load_string(mrb, "5.times { |n| W32Window.create \"Window #{n}\" }");

Compile, run and we have five different uniquely named windows!

Lets take a moment and marvel at what we did here. We pushed creating of new windows using Win32 into the Ruby VM and parameterized the construction of the windows. We didn't need any external window management libraries, a chain of dependencies from a gemfile, didn't need something like FFI creating tenuous bindings between the Ruby VM and an external library. It's all right in front of us in less than 80 lines of code. It's pretty amazing and easy! All we needed to get to where we're at is just the mruby library and the facilities provided with Windows programming.

If this is your first foray into this style of programming you may start to develop questions on why it takes thousands of interdependent NPM, Python, Java or Ruby libraries and hundreds of lines of boilerplate to generate a 'Hello World' in a browser. If you're like me and burnt out over years to decades of overly complicated development, where it takes a whole quarter to show a birthdate this probably feels refreshing and fun again.

Lets keep going and finish this out. The last thing we want to add here are keyword arguments for the window dimensions width and height.

Extracting keyword parameters

It's straightforward and simple extracting positional parameters passed C implemented Ruby methods. It's more complex for keyword parameters which is why I want to detail it here. Most of Ruby's history didn't support method arguments other than positional arguments, a block parameter, and a construction for grouping the 'rest' arguments, like the JavaScript ...args in a function name.

We faked keyword parameters by passing a hash as a parameter into the method. The Ruby interpreter supported this by allowing the removal of the outer braces. This is similar to passing an object to a function in JavaScript While this worked enforcing some keyword parameters and providing defaults ended up with a lot of boilerplate

def foo(args)
  a = args.fetch(:a, 'default value')
  b = args.fetch(:b, nil)
end
foo a: 1, b: 2 # the same as foo({a: 1, b: 2})

Skipping ahead in history, Ruby added support for, default parameters for any positional argument, keyword parameters, keyword parameters with a default, required keyword parameters, and block parameters also supports all of those. A method signature in Ruby can look tremendously complex. This is why the mruby C API looks complicated, as we will see right now for keyword arguments.

We want the full method signature for our create method to look like

def W32Window.create window_title, width:, height:

When I'm working with Ruby I generally create methods with more than one parameter using keyword arguments. I usually put the most important information as the first positional argument and then the rest as keyword arguments.

mrb_get_args uses a special mrb_kwargs type for the definition on how to extract keyword arguments. We use this type instead of an mrb_value when extracting the arguments.

struct mrb_kwargs
{
  uint32_t num;
  mrb_value *values;
  const char *const *table;
  uint32_t required;
  mrb_value *rest;
};

num is the number of keyword arguments in total. values is a pre-created array of mrb_values that we extract the parameter value into, like we did with the string. table is a char*[], an array of string, which are the names of the keyword arguments. required is the number of required keyword arguments.

Starting with the call to mrb_get_args we can work backwards and fill out the rest of the information.

const mrb_kwargs kwargs = { 2, kw_values, kw_names, 2, nullptr };
mrb_get_args(state, "S:", &window_name, &kwargs);

We know we want two keyword arguments and require 2, so we'll use 2 for both places. There won't be a rest param, so that's null. Now we just need the two arrays

const char* kw_names[2] = { "width", "height" };
mrb_value kw_values[2] = {};

Now we reference these parameters in CreateWindowEx instead of hardcoded values. We know we want the mrb_value types in kw_values as integers. We could cast them ourselves, however mruby usually has helpful macros for that already, so lets use them. In this case it's mrb_fixnum, which is directly compatible with standard integers without any casting necessary.

HWND main_window = CreateWindowEx(0, wclass.lpszClassName, RSTRING_PTR(window_name),
                                  main_window_style, CW_USEDEFAULT, CW_USEDEFAULT,
                                  mrb_fixnum(kw_values[0]),
                                  mrb_fixnum(kw_values[1]),
                                  0, 0, GetModuleHandle(nullptr), 0);

Lastly change mrb_load_string to provide the keyword arguments

mrb_load_string(mrb, "5.times { |n| W32Window.create \"Window #{n}\", width: 1024, height: 768 }");

Build, run, and of course everything is the same as before. Change the values of the width and height parameters and they change appropriately, for instance something like

mrb_load_string(mrb, "5.times { |n| W32Window.create \"Window #{n}\", width: n * 100, height: n * 100 }");

Which gives us a predictable 5 windows of increasing size

Celebration!

That's it for our introduction to using the mruby C API. We tied together Win32, mruby and parameterized window creation from Ruby to Windows with just the mruby library in 80 lines of code. Total! Amazing.

While the volume of words here implies there's something complicated happening it really isn't. I'm being especially thorough on explaining all the details, repeating some key points so things stick. Once you understand the concepts you can delete everything, start from scratch and replicate it yourself rapidly in less than an hour the second time, and faster still the third time.

Next up we'll finish this off by turning W32Window.create into a new constructor instead, encapsulate the HWND and HINSTANCE in the instance of the class, add a reference to the mruby W32Window instance into the Win32 window so we can get it back in the main_window_callback, and then change the program behavior so that it exits when all windows close, not any of them.

The full code

#include <windows.h>
#include <stdio.h>
#include "mruby.h"
#include "mruby/compile.h"
#include "mruby/string.h"

bool g_should_quit = false;

LRESULT CALLBACK
main_window_callback(HWND window, UINT message, WPARAM wparam, LPARAM lparam) {
  LRESULT result = 0;
  switch(message) {
  case(WM_CLOSE): {
    PostQuitMessage(0);
    break;
  }
  default: {
    result = DefWindowProc(window, message, wparam, lparam);
  }
  }
  return result;
}

mrb_value
w32_window_create_method(mrb_state* state, mrb_value self) {
  mrb_value window_name;
  mrb_int width;
  mrb_int height;
  const char* kw_names[2] = { "width", "height" };
  mrb_value kw_values[2] = {};
  const mrb_kwargs kwargs = { 2, kw_values, kw_names, 2, nullptr };
  mrb_get_args(state, "S:", &window_name, &kwargs);

  WNDCLASSEX wclass = {};
  wclass.cbSize = sizeof(WNDCLASSEX);
  wclass.lpszClassName = "mainWindowClass";
  wclass.lpfnWndProc = main_window_callback;
  wclass.hInstance = GetModuleHandle(nullptr);
  wclass.style = CS_OWNDC | CS_VREDRAW | CS_HREDRAW;
  RegisterClassEx(&wclass);

  DWORD main_window_style = (WS_OVERLAPPEDWINDOW | WS_VISIBLE);

  HWND main_window = CreateWindowEx(0, wclass.lpszClassName, RSTRING_PTR(window_name),
                                    main_window_style, CW_USEDEFAULT, CW_USEDEFAULT,
                                    mrb_fixnum(kw_values[0]),
                                    mrb_fixnum(kw_values[1]),
                                    0, 0, GetModuleHandle(nullptr), 0);

  return mrb_nil_value();
}

int main() {
  mrb_state *mrb = mrb_open();
  RClass *w32_window_class = mrb_define_class(mrb, "W32Window", mrb->object_class);
  mrb_define_class_method(mrb, w32_window_class, "create",
                          w32_window_create_method, MRB_ARGS_REQ(1));

  mrb_load_string(mrb, "5.times { |n| W32Window.create \"Window #{n}\", width: n * 100, height: n * 100 }");

  while(!g_should_quit) {
    MSG message = {};
    while(PeekMessage(&message, nullptr, 0, 0, PM_REMOVE)) {
      switch (message.message) {
      case (WM_QUIT): {
        g_should_quit = true;
        break;
      }
      default: {
        TranslateMessage(&message);
        DispatchMessage(&message);
        break;
      }
      }
    }
  }

  mrb_close(mrb);

  return 0;
}

Managing a Windows window within mruby Part 1: Win32 window basics

Rory O'Connell — Thu, 21 May 2020 20:16:48 +0000

My current project, a Smalltalk-style Ruby environment, is currently a C program wrapping the mruby VM. Most of the program state and run loop is in C, with the run loop calling the mruby VM once per GUI frame. It looks something like this, abbreviated

mrb_state mruby_state;

int main() {
mruby_state = mrb_open();
setup_windows();
setup_graphics();
while(!done) {
  process_window_messages();
  start_new_frame();
  mrb_load_string(mruby_state, "World.render");
  present_frame();
}
shutdown_graphics();
mrb_close(mruby_state);
return 0;
}

Methods inside the mruby VM call back out to C telling the GUI what to render next frame. Everything else is in C. This works okay though I'm running into issues regarding stability. Since control passes back and forth between the Ruby VM and C I have to be extra careful on the order of operations or I end up crashing the program. What I want to do is remove as much of the C program code as I can, instead pushing the program into the Ruby VM including managing the Windows state and the graphics setup. I'll implement these as Ruby methods written in C and using mruby_data types when necessary. An mruby_data type is a C type which can wrap a C structure of arbitrary data into a Ruby class.

We're going to create a throw away project of exploratory code that you can follow along with! This first part is creating a new window with Win32 that responds to close events using C. The second part we'll push the window management into the mruby VM like I want to achieve. By the end you'll learn some basics about using Win32 and the mruby C API.

First up on the list of conversions is opening and managing a Windows window within the mruby VM. I'll use the base Win32 C API for this. When working with Windows it's common practice for people to reach for a window management library like GLFW. I don't think that's necessary. The Win32 API for window management is refreshingly simple if a bit strange in modern times. It only takes a couple dozen lines of readable C code to create a basic window. The first version of the CreateWindow function, which instructs Windows to create a new window, first appeared with Windows 1.0 in 1984! We still use CreateWindow in the same way that programmers have for the last 36 years.

note (and shilling): significant portions of this post about Win32 come from a chapter in my in-progress book on low level graphics programming.

Project and Compiler Setup

You'll need at least the Visual Studio command line tools installed. We don't need, and I'll argue forever that you never need, the full Visual Studio IDE. You can use whatever editor you're comfortable with. We'll use Microsoft's compiler, cl. It's theoretically possible to do all of this with just Clang on Windows without installing Microsoft's compiler. I haven't tested that much.

We'll need just two files, a main.cpp file and a build.bat file. Starting with a basic main.cpp file using your normal editor

// main.cpp
int main() {
  return 0;
}

Start a new x64 Native Tools Commmand Prompt for VS 2019 from the Windows start menu. This sets up a new shell with the right environment variables for the cl compiler. You can test that it works by entering cl, which prints basic usage information.

cd in that shell window to where you created the main.cpp file. Compile it with cl. We'll turn on creating debug symbols, /Zi, use the latest C++ version the compiler supports, /std:c++latest, turn off RTTI (run-time type information), /GR-, disable the compiler splash screen, /nologo, and enable helpful static checks, /analyze.

cl /Zi /std:c++latest /GR- /nologo /analyze main.cpp

Run that and you'll have a new main.exe file along side the main.cpp file, plus other sundry intermediate compiler object and linkage files. Running the main.exe file doesn't do anything of course. We didn't do anything except immediately exit.

Once you tested a basic main program and the compiler flags work we need just two elements added for accessing the Win32 API. Add #include <windows.h> to the top of main.cpp. This header file defines all the types, function prototypes, and constants for the entire Win32 C API.

We also need to pass the linker some parameters as well. Add /link to the end of your compiler line, which tells cl everything following /link are linker options. We want to generate debug symbols from linked libraries with /DEBUG. Finally we need to link against the library containing the symbols for creating windows, user32.lib. We don't need to specify any library paths, the developer command prompt set up the Windows library paths for us. The full command line looks like

cl /Zi /std:c++latest /GR- /nologo /analyze main.cpp /link /debug user32.lib

To save us from having to find that line in our command line history or retyping it frequently, save that line to a new batch file. Common convention is naming the file build.bat.

That's all we need set up. We're ready to get to work.

Opening a new window

We need just three components to create a new window; creating a callback function for processing events Windows sends to the window, creating a WNDCLASSEX structure defining how the window behaves, and then calling the Win32 CreateWindowEx function.

Starting with the callback function. We register this function when creating a new window. Windows calls this function for processing incoming messages such as the close window message, keyboard and mouse events, and the like. Let's create one that doesn't do anything at the moment and come back to it later. Right underneath #include <windows.h>

LRESULT CALLBACK 
main_window_callback(HWND window, UINT message, WPARAM wparam, LPARAM lparam) {
  LRESULT result = 0;
  return result;
}

The next step is filling out a WNDCLASSEX struct. The Windows API uses a
typical C programming pattern of filling out a struct and passing the address of that struct to a function. We treat the structs as parameters to functions. This is similar to passing an object to a function in JavaScript, and almost identical to using an interface in a function with TypeScript.

A WNDCLASSEX struct passed into the RegisterClassEx registers a window
class within Windows. A window class is a reusable unit for repeatedly creating windows of identical functionality. That's not our use case so we can keep things simple. First create a new WNDCLASSEX struct zero-initialized, and then fill out some members we care about. In the main function

WNDCLASSEX wclass = {};
wclass.cbSize = sizeof(WNDCLASSEX);
wclass.lpszClassName = "mainWindowClass";
wclass.lpfnWndProc = main_window_callback;
wclass.hInstance = GetModuleHandle(nullptr);
wclass.style = CS_OWNDC | CS_VREDRAW | CS_HREDRAW;
RegisterClassEx(&wclass);

The verbosity of the struct member names likely feels alien to you. Microsoft created the Windows API in the early 1980s and used the Hungarian notation naming pattern. With Hungarian notation all variables and members have the data type in the name. This was for reducing type errors. At the time compilers and computers were a great deal slower and we did not have advanced IDEs which understood the types as you were programming. It was a high time cost treating something as the wrong type accidentally and waiting for the compiler to catch it. Hungarian notation fell out of favor and disappeared through the 90s as it's usefulness diminished.

Along the way the structs Windows uses for parameters picked up a common cbSize member. Set this to the sizeof the struct. This is for sanity checking and versioning of functions which use the structs. If you pass a struct to a Windows function and it doesn't recognize the size of it the function fails.

lpszClassName is straightforward. With Hungarian notation, lpsz says two things. lp means 'long pointer', historically 'far pointer'. Both of those terms are meaningless today. sz is 'string, zero terminated'. lpsz is just a standard C char *.

lpfnWndProc is also obvious. lp is again a long pointer, fn is function, so this is a standard function pointer to our callback function from earlier.

hInstance a handle to an identifier of a running program. Since we aren't doing anything interesting we call GetModuleHandle with a null parameter. This returns an HINSTANCE pointing to the currently running program.

The style member is an integer representing the window style and how it behaves. It uses another common C programming pattern of using one number representing multiple preferences at once as a bitmask representing multiple preferences at once as a bitmask with the numbers of the bitmask represented by #define constants or members of an enum.

That's all we need for registering a window class. We call RegisterClassEx with the address of the wclass struct.

Compiling at this point works, running it doesn't do anything. We still have to create the window using CreateWindowEx

DWORD main_window_style = (WS_OVERLAPPEDWINDOW | WS_VISIBLE);

HWND main_window = CreateWindowEx(0, wclass.lpszClassName, "Playground",
                                  main_window_style, CW_USEDEFAULT, CW_USEDEFAULT,
                                  1024, 768,
                                  0, 0, GetModuleHandle(nullptr), 0);

First we create a DWORD, another legacy type which is now unsigned long. Window styles are another bitmask. Here we state we want an overlapped window, which is a collection of styles giving a window a default look. We also want the window visible by default.

Again we aren't doing anything interesting or advanced with our window so we'll leave most of the parameters at 0.

Compiling and running again still doesn't produce anything yet. We're missing one last piece. Windows does create the window successfully. Then it sends the WM_CREATE message to the callback function, main_window_callback. Since all we do in the callback is just return 0 we drop the message. If we don't pass the message back to Windows it doesn't make the window visible.

We won't need much for callback processing. For now all we have to do is send all the messages back to Windows using DefWindowProc.

LRESULT CALLBACK
main_window_callback(HWND window, UINT message, WPARAM wparam, LPARAM lparam) {
  LRESULT result = 0;
  switch(message){
  default: {
    result = DefWindowProc(window, message, wparam, lparam);
  }
  }
  return result;
}

Compile, run and success! You'll see a brief flash of a window before the program exits. You can run the program in a debugger, halting just before returning from main or add a system("pause"); right before returning and you'll see a new blank window of 1024 x 768 pixels.

Processing window messages

Now we have to do a little bit more work for a fully functioning window, processing the messages from the callback function as they come in. We need an evil global variable as a signal that the program is finished. Right after include <windows.h>, before defining the callback function add

bool g_should_quit = false;

Then right after calling CreateWindowEx create a while loop with that variable.

while(!g_should_quit) {
}

Compiling and running at this point you'll get a window and then after a few seconds Windows thinks the program is dead. We see a familiar (Not Responding) in the title bar and in Task Manager.

The program didn't crash. It's still running the while loop just fine. The program isn't responding to messages Windows sends it, so Windows thinks the program isn't functioning currently.

Easy fix now is processing the messages sent to the window. We can do that with the PeekMessage function which pulls messages sent to the window off of the message queue. Create an inner loop inside the existing while loop

while(!g_should_quit) {
  MSG message = {};
  while(PeekMessage(&message, nullptr, 0, 0, PM_REMOVE)) {

  }
}

PeekMessage returns 0 when there are no more messages. Otherwise, the loop runs once for each message in the queue. We aren't doing anything special with the messages or are doing multi threaded window management so we leave most of the defaults at 0. The last parameter says remove the message from the queue when we process it.

Now lets fill out the rest of this final loop. The only message we care about at this point is the WM_QUIT message. Windows sends this message when the user clicks the close button on the window.

switch (message.message) {
case (WM_QUIT): {
  g_should_quit = true;
  break;
}
default: {
  TranslateMessage(&message);
  DispatchMessage(&message);
  break;
}
}

Here we switch on the message type represented by an integer. We capture the WM_QUIT message, set the state signal that we're quitting. For all other
messages we pass the message back to the default handlers using the Microsoft recommended TranslateMessage and DispatchMessage functions.

Running the program at this point we have an active window! The program loops over the message queue until the user closes the window with the close button. The window closes properly. Resizing is a bit strange. That's because we aren't redrawing the window when Windows tells us we have to redraw it with a WM_PAINT message. We don't actually care about that since we'll use something else for drawing the window contents.

However there's one last quirk to the Win32 API. You'll notice that when running the program from a terminal your program process quits yet the terminal does not return and you must terminate it with Ctrl-C. This is because your program did not notify Windows your program finished. To fix this we must call the function PostQuitMessage from the window callback. This is a simple addition. In main_window_callback, add a case for capturing the WM_CLOSE event.

case(WM_CLOSE): {
  PostQuitMessage(0);
  break;
}

And that's it! Here's the entire program for creating a functional basic Win32 window

#include <windows.h>

bool g_should_quit = false;

LRESULT CALLBACK
main_window_callback(HWND window, UINT message, WPARAM wparam, LPARAM lparam) {
  LRESULT result = 0;
  switch(message) {
  case(WM_CLOSE): {
    PostQuitMessage(0);
    break;
  }
  default: {
    result = DefWindowProc(window, message, wparam, lparam);
  }
  }
  return result;
}

int main() {
  WNDCLASSEX wclass = {};
  wclass.cbSize = sizeof(WNDCLASSEX);
  wclass.lpszClassName = "mainWindowClass";
  wclass.lpfnWndProc = main_window_callback;
  wclass.hInstance = GetModuleHandle(nullptr);
  wclass.style = CS_OWNDC | CS_VREDRAW | CS_HREDRAW;
  RegisterClassEx(&wclass);

  DWORD main_window_style = (WS_OVERLAPPEDWINDOW | WS_VISIBLE);

  HWND main_window = CreateWindowEx(0, wclass.lpszClassName, "Playground",
                                    main_window_style, CW_USEDEFAULT, CW_USEDEFAULT,
                                    1024, 768,
                                    0, 0, GetModuleHandle(nullptr), 0);

  while(!g_should_quit) {
    MSG message = {};
    while(PeekMessage(&message, nullptr, 0, 0, PM_REMOVE)) {
      switch (message.message) {
      case (WM_QUIT): {
        g_should_quit = true;
        break;
      }
      default: {
        TranslateMessage(&message);
        DispatchMessage(&message);
        break;
      }
      }
    }
  }

  return 0;
}

We can see plainly all the components necessary for creating a basic Win32 window. Now the next step is creating an mruby environment and setting it up so all of the management and message processing is within the mruby VM. We'll use this exploratory code project on figuring that out. Armed with that knowledge I can go back to the original mruby GUI project and refactor it with the window managment within the mruby VM.

One last polish thing. By default on a high resolution display, like a 4k monitor or high DPI laptop display, Windows will pixel double any window. This makes the window readable on a high DPI display but it makes the window blurry. We can't see this since we aren't drawing anything into the window at the moment. Fixing this is a simple function call. Add

SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2);

right before CreateWindow. This signals to Windows that the application is high DPI aware and handles it appropriately.

note if you want to remove the console window from your program, add the linker options /SUBSYSTEM:windows and /ENTRY:mainCRTStartup. This signals to the linker assembling your program to use the main function of the program as the entry point and the main window controls the application.

Ruby GUI progress: Leaking worlds, naming is hard

Rory O'Connell — Wed, 20 May 2020 22:12:40 +0000

First and most importantly this project progressed enough that it now needs a catchy, searchable name. I have a couple candidates that are fine though they don't feel right. There are Latin words pyrope which is a kind of red or rust colored gem though inferior to a ruby gem; and punicus which sounds better though it has multiple meanings. Along with the color bright red it may also relate to old Carthage and the Roman bloodlust for Carthaginian genocide which isn't what I want to evoke.

Now the less important stuff

(dev.to embedded gifs aren't functioning at the moment)

https://dev-to-uploads.s3.amazonaws.com/i/7afo799od7nrmgegw90v.gif

I've made a tremendous amount of progress in a few days it's hard to talk about where things are at. I'll detail the most interesting thing I came across the past few days, a few quick hits and then where I'm going next.

I'm using the Dear ImGUI library for creating the GUI.

ocornut / imgui

Dear ImGui: Bloat-free Graphical User interface for C++ with minimal dependencies

Dear ImGui

"Give someone state and they'll have a bug one day, but teach them how to represent state in two separate locations that have to be kept in sync and they'll have bugs for a lifetime." -ryg

(This library is available under a free and permissive license, but needs financial support to sustain its continued improvements. In addition to maintenance and stability there are many desirable features yet to be added. If your company is using Dear ImGui, please consider reaching out.)

Businesses: support continued development and maintenance via invoiced sponsoring/support contracts
E-mail: contact @ dearimgui dot com
Individuals: support continued development and maintenance here. Also see Funding page.

The Pitch - Usage - How it works - Releases & Changelogs - Demo - Getting Started & Integration
Gallery - Support, FAQ - How to help - Funding & Sponsors - Credits - License
Wiki - Extensions -

…

View on GitHub

It's a tiny easily embedded interface library written in an orthodox C++, or C+, style. That is, almost entirely functions and structs without any of the C++ nightmares. Im means immediate mode GUI, in contrast to retained mode. The primary difference between the two is what controls the state of the interface. Most people are used to working with something that looks like a retained mode GUI. The user of a retained mode interface notifies an underlying system of changes. When notifying GUI system of changes the GUI library changes internal data structures and rebuilds lists of commands for drawing the interface. Working with the browser DOM is a great example of retained mode style. We tell the browser presentation engine when things change by modifying the DOM elements, not by telling the browser how to render a page directly.

Immediate mode style GUI does away with that state and hands the user of the API complete control of how to draw all the elements. Instead of notifying a system when state changes, with an immediate mode design the GUI code you write is instead executed linear sequence every frame. It's best shown with an example, here from the Dear ImGUI demonstration

if (ImGui::BeginMenuBar())
{
    if (ImGui::BeginMenu("Menu"))
    {
        ShowExampleMenuFile();
        ImGui::EndMenu();
    }
    if (ImGui::BeginMenu("Examples"))
    {
        ImGui::MenuItem("Main menu bar", NULL, &show_app_main_menu_bar);
        ImGui::MenuItem("Console", NULL, &show_app_console);
        ImGui::MenuItem("Log", NULL, &show_app_log);
        ImGui::MenuItem("Simple layout", NULL, &show_app_layout);
        ImGui::MenuItem("Property editor", NULL, &show_app_property_editor);
        ImGui::MenuItem("Long text display", NULL, &show_app_long_text);
        ImGui::MenuItem("Auto-resizing window", NULL, &show_app_auto_resize);
        ImGui::MenuItem("Constrained-resizing window", NULL, &show_app_constrained_resize);
        ImGui::MenuItem("Simple overlay", NULL, &show_app_simple_overlay);
        ImGui::MenuItem("Manipulating window titles", NULL, &show_app_window_titles);
        ImGui::MenuItem("Custom rendering", NULL, &show_app_custom_rendering);
        ImGui::MenuItem("Documents", NULL, &show_app_documents);
        ImGui::EndMenu();
    }
    if (ImGui::BeginMenu("Tools"))
    {
        ImGui::MenuItem("Metrics", NULL, &show_app_metrics);
        ImGui::MenuItem("Style Editor", NULL, &show_app_style_editor);
        ImGui::MenuItem("About Dear ImGui", NULL, &show_app_about);
        ImGui::EndMenu();
    }
    ImGui::EndMenuBar();
}

Reading this top to bottom you know exactly what's going on. Two points of interest. One, the if() calls around ImGUI functions generally mean 'if this element is visible'. If that element is completely obscured in some way it doesn't execute that code path. Amazingly simple! The other interesting point is Dear ImGUI elements usually take a boolean parameter. This is a reference to an address of memory representing if the element should be displayed or disabled. The interface for creating a new window is ImGui::Begin("Ruby Eval", &ruby_eval_open). The second parameter becomes false when the user closes the window. We can re-open the window whenever we want by setting ruby_eval_open to true.

(This pattern works fantastically in C and comes back to bite us when we're in Ruby land. Discussions for another day)

Casey Muratori describes the differences and benefits of an immediate mode in great detail here

Setting aside HN style nonsense on the computational efficiency or wastefulness of this pattern, the benefit to this is we have full control over what we want to draw when and the clear simplicity of it.

Back to making the GUI work with Ruby. It's a straightforward process making an mruby class in C in which calling the methods on the class in Ruby execute C code. For now I'm generally mapping the ImGUI functions to a GUI module one to one.

In a World...

The main program loop is in C. It looks something like this, abbreviated

while(!done) {
  process_window_messages();
  begin_new_frame();
  mrb_load_string(mrb, "World.render");
  render_frame();
}

The important bit here is mrb_load_string. It's essentially an eval into the mruby state. Surrounding the call processes incoming Windows messages, sets up the next frame, then renders the frame. Presently World.render is the entry point for each frame from the Ruby side. World is another simple construction. It maintains a list of all the open windows. When we call World.render it iterates over all of the open windows calling render on each.

module World
  @open_windows = []

  def self.add_window window
    raise unless window.respond_to? :render

    @open_windows.push window unless @open_windows.include? window
  end

  def self.remove_window window
    @open_windows.delete window
  end

  def self.render
    # TODO see if current active window respond_to? menu_bar,
    # otherwise render this
    GUI.main_menu do
      GUI.menu("Tools") do
        GUI.menu_item "Class Browser", "Ctrl+I" do
          ClassBrowser.open
        end

        GUI.menu_item "Open Transcript", "Ctrl+T" do
          Transcript.open
        end

        GUI.menu_item "Open Stats", "" do
          Stats.open
        end
      end
    end

    @open_windows.each { |window| window.render }
  rescue => ex
    puts ex
  end
end

When you want to open a window, call World.add_window thing. Closing it is World.remove_window thing. Simple and straight forward.

Implementing a render method is a simple set of ImGUI calls. For example, this is the full Transcript, a global console-like thing where you can print stuff to

module Transcript
  @lines = []

  def self.add obj
    @lines.push obj.to_s
  end

  def self.clear
    @lines = []
  end

  def self.open
    World.add_window self
  end

  def self.close
    World.remove_window self
  end

  def self.render
    GUI.new_window 'Transcript' do
      @lines.each { |line| GUI.text line }
    end
  end
end

This all works fine and I was reasonably satisfied with it so far. Until one time I left the program open for several hours I noticed the program acquired multiple gigabytes of working memory. It usually allocates about 300kb total. Classic memory leak somewhere. Getting to the heart of why is a long saga detailed in this short Github exchange.

Effective ways on running Ruby code from within C without leaking Proc objects? #5001

RoryO posted on May 17, 2020

Short summary

mrb_load_string, related functions and the typical run mruby code from C patterns create an RProc object on every call which is never marked for GC. There's an easy reproduction case with a simple C program

#include "stdio.h"
#include "ext/mruby.h"
#include "ext/mruby/compile.h"
#include "ext/mruby/gc.h"

int main() {
    mrb_state *mrb = mrb_open();
    for(int i = 0; i < 100000; ++i) {
        mrb_load_string(mrb, "nil");
        if(i % 100 == 0) {
            printf("%zi\n", mrb->gc.live);
        }
    }
    
    return 0;
}

Longer explanation

I'm working on embedding mruby in a GUI. The C portion of program sets up all the initial rendering, then passes control to the mruby VM, then renders the frame after the VM finishes. I call the ruby VM exactly once each frame from C with one entry point. My main program loop looks roughly like

while(!done) {
  setup_frame();
  mrb_load_string(mrb, "World.render");
  render_frame();
}

And this works wonderfully! The fast C code path does the intensive graphics calculations and rendering, and I have one entry point which kicks off processing the VM every 'tick' with World.render Leaving out a lot of unnecessary surrounding context here to get at the heart of the matter.

After being so happy for a couple days on how easy this was going I left my program overnight, coming back the program taking up multiple gigabytes of memory where it usually only takes a few hundred kb. Tell tale memory leak of some kind. I did a lot of digging within my own C code as that's the most likely answer and came up with nothing.

Looking at the live object count every frame I noticed the live object count never decreases. I started digging in the Ruby code thinking I created object islands and came up with nothing. Finally I changed my loop to do mrb_load_string(mrb, "nil"); and much to my surprise the object count increased linearly infinitely just as before when the mruby VM shouldn't do anything at all!

Digging some more into ObjectSpace while simply calling nil every frame I found that T_PROC objects grow indefinitely. After a few minutes of running

{:TOTAL=>73728, 
:FREE=>206, 
:T_OBJECT=>2, 
:T_CLASS=>59, 
:T_MODULE=>10, 
:T_ICLASS=>14, 
:T_SCLASS=>75, 
:T_PROC=>73285, 
:T_ARRAY=>2, 
:T_HASH=>2, 
:T_STRING=>23, 
:T_EXCEPTION=>2, 
:T_ENV=>44, 
:T_DATA=>3, 23=>1}

Looking at the definition of mrb_load_string and others related it it's usually the same sequence of function calls: creating a new parser context, parsing the string, generating a proc object, run the code in the vm, free the parser and context. I replicated this replacing mrb_load_string in my loop

mrbc_context* ctx = mrbc_context_new(state->ruby_state);
mrb_parser_state *parser = mrb_parse_string(state->ruby_state, "World.render", ctx);
RProc *proc = mrb_generate_code(state->ruby_state, parser);
mrb_value retval = mrb_vm_run(state->ruby_state, proc, mrb_top_self(state->ruby_state), 0);

mrb_pool_close(parser->pool);
mrbc_context_free(state->ruby_state, ctx);

And realized there are the infinitely growing Proc objects created. Digging through old issues I had the idea of calling mrb_gc_arena_save/mrb_gc_arena_restore before and after the loop... and this works! The object count stabilizes over time. Hurray, problem solved!

However I'm not completely satisfied. Going back to the old 'principle of least surprise' I found it highly surprising that the typical patterns used in functions like mrb_load_string leak objects.

Some questions

It feels like a mistake that functions like mrb_load_string and it's relatives leak Proc objects on every call. Should we do a gc save/restore within these functions?
Is there a better way to invoke a Ruby method from C without creating a new RProc object?
Alternately, is there a way we could mark the RProc used for execution as black immediately after running it in the VM so it becomes GC'd next cycle? This feels like it's crossing too many boundaries however.

View on GitHub

The short answer is this innocent looking C call

mrb_load_string(mrb, "World.render");

Which it turns out any C function named mrb_load_* creates an RProc object in the current mruby state. However, that RProc is not garbage collected at any point! For reasons I sort understand this document details the situation. However it feels surprising that the mrb_load_* function calls don't automatically protect against that situation.

Going back to the main loop, we call mrb_load_string every frame, yielding to the World object for rendering all the windows. That generates an RProc object in the VM which the garbage collector never collects. We do the at least 60 times a second, so we're leaking 60 RProc objects a second. A basic Ruby object is tiny, 36 bytes or so which is why this behavior was not noticeable.

I've since added basic GC stats into the interface so I can observe such things

https://dev-to-uploads.s3.amazonaws.com/i/jam8uak08klab6mwbvum.gif

Next up

As it stands currently this is primarily a C program driving the mruby state as shown by the main program loop is in C. I want to flip this around where the main program loop is in Ruby which calls back to C code when necessary. I want the C main function to look something like

int main() {
  setup_state();
  mrb_load_string(mrb, "GUI.start");
  cleanup();
  return 0;
}

And then the Ruby side looking something like

class GUI
  def self.start
    while is_running do
      process_window_events
      begin_next_frame
      render
      present_frame
    end
  end
end

I think this will take a significant amount of work and I know it will pay off later. Reading through past mruby issues and recommendations by matz the general solution to most of the integration problems is 'push what you're doing into the mruby VM instead of C'.

I didn't think of moving the loop into ruby this way until I saw this demonstration of a madman using mruby for creating a Sega Dreamcast game. This combination of esoteric things, homebrew Dreamcast development and mruby, make me quite happy it exists.

yujiyokoo / mrbtris-dreamcast

mrbtris: Sample game for Sega Dreamcast written in Ruby

mrbtris is a simple game for the Sega Dreamcast which is written in Ruby as an proof-of-concept of using the mruby implementation on the Sega Dreamcast. This project was written by @yujiyokoo.

This project is built on the top of KallistiOS (KOS), which is the low-level library used to interact with the Sega Dreamcast hardware. Usually, programs written for the Sega Dreamcast are in C/C++, this project aims to demonstrate the use of Ruby source code targeting the Sega Dreamcast.

This project aims to provide a simple example of how to use KallistiOS (KOS) API and mruby together.

Demonstration

Below you may find a video of this game running on the real hardware (early version)

TODO

Make an mrbgem for the Dreamcast specific things
Create unit tests
Use more Sega Dreamcast features

Building

mrbtris uses KallistiOS (KOS) and mruby…

View on GitHub

Integrated Ruby GUI day two: I guess I'm doing this

Rory O'Connell — Thu, 14 May 2020 08:14:14 +0000

This project keeps me up at night. I keep thinking of all the possibilities and how to proceed. A little experiment turned into an obsession. I'll provide a view of the work log of an obsession.

Have a basic class and method browser up and going. It's live and here I play around with infamous ways of dynamically updating classes. A huge problem I have in the back of my mind is I'm using ObjectSpace.each_object for building the class list. Looking at the C code that method does a full GC before iterating the objects. This is a huge problem as it is currently doing a full GC every. single. frame. 60 times a second. Leaving the class browser open a few minutes the FPS tanks, and immediately springs back hiding the browser window. There isn't a memory leak, it may be memory fragmentation on the VM side.

There's a few more GUI methods exposed to the Ruby VM. I have a lot more to go, I'm adding them as I need them. I'm not happy with the interface at the moment, they're exposed basically one to one. The GUI methods make sense for C and feel awkward in Ruby. I predict I'll change them frequently on the Ruby side.

Right now there's one bootstrap file. Currently the program reads every Ruby file in the ruby directory and throws it at the VM. Not elegant, works for now. As I can pull more things into the VM directly and make it more robust I can add Ruby code into the VM startup; like sys-v init scripts or autoexec.bat files.

module Inspector
  @selected = nil
  @konst = nil

  def self.render
    a = []
    # these mirror the imgui api almost exactly which doesn't feel like ruby
    # the imgui api makes sense with C. i'll come up with better constructions when i get
    # more insight
    GUI.begin_window("Class list") do
      GUI.begin_child("Classes", 400, 0) do
        # each_object triggers a full GC, so we're doing a full GC
        # each frame the class list is visibe :/
        # we must fix this later. after several minutes fps tanks
        # see gc.c mrb_objspace_each_objects
        # will need our own object iterator coming from the C side
        # which doesn't do a full GC first
        ObjectSpace.each_object(Class) { |k| a.push k.name unless k.name.nil? }
        a.sort.each do |n|
          # this is a yucky api
          if GUI.selectable(n, @selected == n)
            @selected = n
            @konst = Kernel.const_get(@selected.to_sym)
          end
        end
      end

      if @selected
        GUI.same_line
        GUI.begin_child("Class methods", 400, 0) do
          @konst.methods(false).sort.each do |m|
            GUI.text m.to_s
          end
        end

        GUI.same_line
        GUI.begin_child("Instance methods", 400, 0) do
          @konst.instance_methods(false).sort.each do |m|
            GUI.text m.to_s
          end
        end
      end
    end
  end
end

Speaking of VM state I have a long term worry about saving the state of the VM and reconstituting it later, like how Pharo handles images. MRuby has a far better design than the mainline VM as the state of the VM is in one mrb_state type. The mainline Ruby VM has a global state like OpenGL. However an mrb_state is a massive series of pointers. Serializing it means following all the pointers of pointers to pointers and copying the memory at the end of the pointer chain. It looks like the mruby-thread library does at least part of that.

There's also the manner of the original Ruby source becoming lost once it's compiled and placed into the VM state. That makes viewing source on methods impossible unless there's a secondary record kept. I'll look into how Pharo handles it.

So much to do.

I have a book to write, damnit.

A new Smalltalk style environment for Ruby: the beginning

Rory O'Connell — Wed, 13 May 2020 03:15:44 +0000

The past months I embarked on a book writing project on accident; a book on low level graphics programming. It uses Vulkan though the concepts focus on graphics programming, not Vulkan specifically. I looked at all the notes I gathered the past couple years and realized I had all the material I wished I had when I started learning something new. I estimate it's about one third written, about 40,000 words or a bit over 100 pages so far, leaving out diagramming, proofing and editing. I never say anything about what I'm doing until I'm sure I'm committing to it, so I'm publicly committed to finishing it.

It's a slog writing a book full time. There's bursts of activity and then I have to take a break and focus my mind on something else. I've felt confident lately on my graphics programming and low level programming skills so I attempted something ambitious.

I always loved working in Smalltalk environments. The super tight integration between code, the environment, the debugger, and the editor all being one and the same is so powerful. Modern tooling tries to get there and always fails because today's systems aren't designed with that integration in mind. We're frantically gluing together disparate components trying to achieve the same situation Smalltalk already had. Emacs is pretty close. A modern browser with Javascript is closer than any other major technology we've had before but will never reach the same integration as Smalltalk or even Emacs due to fundamentally how a browser works.

Working within Ruby environments exasperates the disparate component issue. Ruby as a language takes strong influences from the Smalltalk language. Like a Smalltalk environment the only definitive state of a Ruby environment is the state of the VM as it's running. Anyone who's worked with Ruby knows the normal edit file -> run in Ruby VM loop has a fundamental problem. What you write in a separate file may not be what actually runs in the VM at runtime.

So my current side project is exploring a question. Is it possible to build a Ruby environment like a Smalltalk environment?

Here's an example of about three full time days of work without knowing anything in advance about MRuby. Here I have an GUI and MRuby VM connected. Right now it's brittle and will crash easily with the right Ruby incantation. Still, this is a live MRuby VM wrapped in a GUI and the GUI is (currently partially) driven by the Ruby VM. Here you can see using the GUI modifies the state of the Ruby environment and then the GUI reflects the change back since the GUI reads the Ruby environment. Even though it's super hacked together it already feels astonishingly similar to the Squeak or Pharo Smalltalk environments.

This is becoming a really, really cool project I'm surprised nobody did yet from all my research. It's been keeping me up at night with the possibilities.

I still have a book to write though.