wxruby3 1.7.0 → 1.8.1

data/rakelib/lib/typemap/mb_conv.rb

@@ -0,0 +1,58 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+###
+# wxRuby3 Common typemap definitions
+###
+
+require_relative '../core/mapping'
+
+module WXRuby3
+
+  module Typemap
+
+    module MBConv
+
+      include Typemap::Module
+
+      # wxMBConv classes are used for string text encoding conversion.
+      # We do not want to map these in wxRuby3 though as that serves little purpose there.
+      # So there are wxRuby3 specific versions implemented that get mapped to the actual
+      # wxw instances by the type mappings below.
+
+      define do
+
+        map 'const wxMBConv&' => 'Wx::MBConv' do
+
+          add_header_code <<~__CODE
+            WXRUBY_EXPORT std::unique_ptr<wxMBConv> wxRuby_MBConv2wxMBConv(VALUE rb_val);
+            __CODE
+
+          map_in temp: 'std::unique_ptr<wxMBConv> tmp_mbc',
+                 code: <<~__CODE
+              tmp_mbc = wxRuby_MBConv2wxMBConv($input);
+              if (!tmp_mbc)
+              {
+                rb_raise(rb_eArgError, "Invalid MBConv value for %i", $argnum-1);
+              }
+              else
+              {
+                $1 = tmp_mbc.get();
+              }
+            __CODE
+
+          map_typecheck precedence: 'POINTER', code: <<~__CODE
+            std::unique_ptr<wxMBConv> mbc = wxRuby_MBConv2wxMBConv($input);
+            $1 = mbc ? true : false;
+            __CODE
+
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/rakelib/prepost.rake

@@ -56,27 +56,18 @@ namespace 'wxruby' do
         if WXRuby3.config.windows?
           if WXRuby3.config.get_config('with-wxwin')
             WXRuby3::Post.create_startup <<~__CODE
-              begin
-                require 'ruby_installer'
-                if RubyInstaller::Runtime.respond_to?(:add_dll_directory)
-                  RubyInstaller::Runtime.add_dll_directory('#{File.expand_path('ext')}')
-                else
-                  RubyInstaller::Build.add_dll_directory('#{File.expand_path('ext')}')
-                end
-              rescue LoadError
-              end
+              #{WXRuby3::Post.setup_add_dll_directory(File.expand_path(File.join('ext', 'lib')))}
+              #{WXRuby3::Post.setup_adjust_wx_prefix}
               __CODE
           elsif !WXRuby3.config.get_cfg_string('wxwin').empty? && File.directory?(WXRuby3.config.get_cfg_string('wxwininstdir'))
             WXRuby3::Post.create_startup <<~__CODE
-              begin
-                require 'ruby_installer'
-                if RubyInstaller::Runtime.respond_to?(:add_dll_directory)
-                  RubyInstaller::Runtime.add_dll_directory('#{WXRuby3.config.get_cfg_string('wxwininstdir')}')
-                else
-                  RubyInstaller::Build.add_dll_directory('#{WXRuby3.config.get_cfg_string('wxwininstdir')}')
-                end
-              rescue LoadError
-              end
+              #{WXRuby3::Post.setup_add_dll_directory(WXRuby3.config.get_cfg_string('wxwininstdir'))}
+              __CODE
+          end
+        else
+          if WXRuby3.config.get_config('with-wxwin')
+            WXRuby3::Post.create_startup <<~__CODE
+              #{WXRuby3::Post.setup_adjust_wx_prefix}
               __CODE
           end
         end
@@ -84,19 +75,20 @@ namespace 'wxruby' do
     end
 
     task :install do
-      if WXRuby3.config.windows? && WXRuby3.config.get_config('with-wxwin') && !Rake::FileUtilsExt.nowrite_flag
-        File.open(File.join(WXRuby3.config.get_cfg_string('siterubyver'), 'wx/startup.rb'), 'w') do |f|
-          f.puts <<~__CODE
-            begin
-              require 'ruby_installer'
-              if RubyInstaller::Runtime.respond_to?(:add_dll_directory)
-                RubyInstaller::Runtime.add_dll_directory('#{WXRuby3.config.get_cfg_string('siterubyverarch')}')
-              else
-                RubyInstaller::Build.add_dll_directory('#{WXRuby3.config.get_cfg_string('siterubyverarch')}')
-              end
-            rescue LoadError
-            end
-            __CODE
+      if WXRuby3.config.get_config('with-wxwin') && !Rake::FileUtilsExt.nowrite_flag
+        if WXRuby3.config.windows?
+          File.open(File.join(WXRuby3.config.get_cfg_string('siterubyver'), 'wx/startup.rb'), 'w') do |f|
+            f.puts <<~__CODE
+              #{WXRuby3::Post.setup_add_dll_directory(WXRuby3.config.get_cfg_string('siterubyverarch'))}
+              #{WXRuby3::Post.setup_adjust_wx_prefix}
+              __CODE
+          end
+        else
+          File.open(File.join(WXRuby3.config.get_cfg_string('siterubyver'), 'wx/startup.rb'), 'w') do |f|
+            f.puts <<~__CODE
+              #{WXRuby3::Post.setup_adjust_wx_prefix}
+              __CODE
+          end
         end
       end
     end

data/rakelib/prepost.rb

@@ -24,6 +24,26 @@ module WXRuby3
       end
     end
 
+    def self.setup_add_dll_directory(dll_directory)
+      <<~__CODE
+        begin
+          require 'ruby_installer'
+          if RubyInstaller::Runtime.respond_to?(:add_dll_directory)
+            RubyInstaller::Runtime.add_dll_directory('#{dll_directory}')
+          else
+            RubyInstaller::Build.add_dll_directory('#{dll_directory}')
+          end
+        rescue LoadError
+        end
+        __CODE
+    end
+
+    def self.setup_adjust_wx_prefix
+      <<~__CODE
+        ENV['WXPREFIX'] = File.realpath(File.join(__dir__, '..', '..', 'ext'))
+        __CODE
+    end
+
   end
 
 end

data/samples/event/threaded.rb

@@ -12,20 +12,18 @@
 require 'wx'
 
 # This simple sample demonstrates how to use Ruby (green) threads
-# to execute non-GUI code in parallel with a wxRuby
+# or fibers to execute non-GUI code concurrently with a wxRuby
 # GUI. This strategy is useful in a number of situations:
 # 
 # * To keep the GUI responsive whilst computationally intensive
 #   operations are carried out in the background
 # * To keep the GUI responsive while waiting for networking operations
-#   to complete 
-# 
-# The basic problem is that, as with other Ruby GUI toolkits, non-GUI
-# threads will not, by default, get allocated time to run while Ruby is
-# busy in Wx code - the main wxRuby event loop. Strategies to deal with
-# this include using non-blocking IO, and, more generically, using
-# wxRuby's Timer class to explicitly allocate time for non-GUI threads
-# to run. The latter technique is shown here.
+#   to complete
+#
+# This sample showcases how to use Ruby threading (Thread or Ractor) or
+# cooperative concurrency (Fiber) in a wxRuby GUI application, how to
+# communicate thread safely with the main thread and, if needed, how to
+# provide processing time for non-GUI threads of execution.
 
 module Threaded
 
@@ -51,42 +49,244 @@ end
 
 # This frame shows a set of progress bars which monitor progress of
 # long-running tasks. In this example, this long-running task is
-# emulated by simply sleep-ing for random periods, but could equally be
-# downloading from a socket or parsing a file.
+# a (partially) simulated word counter, but could equally be
+# downloading from a socket or anything else requiring substantial
+# computation or blocking IO operations.
 class ProgressFrame < Wx::Frame
-  STEPS = 20
+
+  module ID
+    include Wx::IDHelper
+    RUN_GT_WITH_CUSTOM_EVENT = self.next_id
+    RUN_GT_WITH_ASYNC_CALL = self.next_id
+    RUN_GT_WITH_QUEUE = self.next_id
+    RUN_FIBER_YIELD = self.next_id
+    RUN_FIBER_UPDATE = self.next_id
+    RUN_RACTOR_THREADS = self.next_id
+  end
+
+  WORKERS = 8
+  STEPS = 100
+
+  # word count simulator
+  class Simulator
+    class << self
+      def run(timeslice)
+        start = Time.now
+        count = 0
+        # use max timeslice time to analyze max 100 files
+        100.times do
+          text = File.read(__FILE__)
+          text.gsub(/\w+/) { count += 1; '' }
+          break unless (Time.now - start) < timeslice
+        end
+        count
+      end
+    end
+  end
+
   def initialize
-    super(nil, :title => 'Threading demo')
+    super(nil, :title => 'Threading demo', size: [600, 400])
 
     self.icon = Wx.Icon(:sample, Wx::BITMAP_TYPE_XPM, art_path: File.join(__dir__, '..'))
 
+    menuFile = Wx::Menu.new
+    helpMenu = Wx::Menu.new
+    helpMenu.append(Wx::ID_ABOUT, "&About...\tF1", "Show about dialog")
+    gt_submenu = Wx::Menu.new
+    gt_submenu.append(ID::RUN_GT_WITH_CUSTOM_EVENT, "Run with custom event", 'Run Green threads simulation with custom events')
+    gt_submenu.append(ID::RUN_GT_WITH_ASYNC_CALL, "Run with async calls", 'Run Green threads simulation with asynchronous calls')
+    gt_submenu.append(ID::RUN_GT_WITH_QUEUE, "Run with thread queue", 'Run Green threads simulation with thread queue')
+    @mi_gt = menuFile.append_sub_menu(gt_submenu, "Run &Green Threads", 'Run simulation using standard Ruby Green threads')
+    fb_submenu = Wx::Menu.new
+    fb_submenu.append(ID::RUN_FIBER_YIELD, "Run Fibers with yield", 'Run Ruby fibers with update through yield')
+    fb_submenu.append(ID::RUN_FIBER_UPDATE, "Run Fibers with update", 'Run Ruby fibers with direct GUI update')
+    @mi_fb = menuFile.append_sub_menu(fb_submenu, "Run &Fibers", 'Run simulation using Ruby Fibers')
+    @mi_rt = menuFile.append(ID::RUN_RACTOR_THREADS, "Run &Ractor Threads", 'Run simulation using Ruby Ractor threads')
+    menuFile.append_separator
+    menuFile.append(Wx::ID_EXIT, "E&xit\tAlt-X", "Quit this program")
+    menuBar = Wx::MenuBar.new
+    menuBar.append(menuFile, "&File")
+    menuBar.append(helpMenu, "&Help")
+    set_menu_bar(menuBar)
+
+    create_status_bar
+
     @gauges = []
+    @workers = []
+    @queue = nil
     panel = Wx::Panel.new(self)
     sizer = Wx::BoxSizer.new(Wx::VERTICAL)
     # progress update handler
     evt_update_progress(:on_progress_update)
-    frame = self
-    # show ten gauges
-    10.times do |gauge_ix|
-      gauge = Wx::Gauge.new(panel, :range => STEPS)
-      # For each gauge, start a new thread in which the task runs
-      Thread.new do 
+    # show a gauge for each worker
+    WORKERS.times do
+      gauge = Wx::Gauge.new(panel, size: [-1, 30], :range => STEPS)
+      @gauges << gauge
+      sizer.add(gauge, 0, Wx::GROW|Wx::ALL, 2)
+    end
+    panel.sizer = sizer
+    sizer.fit(panel)
+
+    evt_menu Wx::ID_EXIT, :on_quit
+    evt_menu Wx::ID_ABOUT, :on_about
+    evt_menu_range ID::RUN_GT_WITH_CUSTOM_EVENT, ID::RUN_GT_WITH_QUEUE, :on_run_green_threads
+    evt_menu_range ID::RUN_FIBER_YIELD, ID::RUN_FIBER_UPDATE, :on_run_fibers
+    evt_menu ID::RUN_RACTOR_THREADS, :on_run_ractor_threads
+
+    evt_thread Wx::ID_ANY, :on_thread_event
+
+    evt_idle :on_idle
+  end
+
+  private def start_run
+    @mi_gt.enable(false)
+    @mi_fb.enable(false)
+    @mi_rt.enable(false)
+    reset_gauges
+    @total = 0
+    @run_start = Time.now
+  end
+
+  private def end_run(total)
+    set_status_text("#{Time.now - @run_start} seconds | #{total} words counted")
+    @mi_gt.enable
+    @mi_fb.enable
+    @mi_rt.enable
+    @queue = nil
+    @workers.clear
+    self.refresh
+  end
+
+  def on_run_green_threads(evt)
+    start_run
+    @queue = Thread::Queue.new if evt.id == ID::RUN_GT_WITH_QUEUE
+    # run a Thread for each worker
+    @workers = (0...WORKERS).collect do |worker|
+      # For each worker, start a new thread in which the task runs
+      Thread.new(evt.id, evt.id == ID::RUN_GT_WITH_QUEUE ? @queue : self) do |evt_id, queue_or_frame|
         # The long-running task
+        count = 0
         STEPS.times do | i |
-          sleep rand(100) / 50.0
+          # simulate processing step
+          count += Simulator.run(0.1) # give each processing cycle a maximum timeslice of 100 msec
           # Update the main GUI asynchronously (more ways than 1)
-          if (gauge_ix % 2) == 0
-            frame.event_handler.queue_event(ProgressUpdateEvent.new(i+1, gauge_ix))
+          case evt_id
+          when ID::RUN_GT_WITH_QUEUE
+            queue_or_frame << [worker, i+1]
+          when ID::RUN_GT_WITH_CUSTOM_EVENT
+            queue_or_frame.event_handler.queue_event(ProgressUpdateEvent.new(i+1, worker))
+          else # ID::RUN_GT_WITH_ASYNC_CALL
+            queue_or_frame.call_after(:update_gauge, worker, i+1)
+          end
+        end
+        count
+      end
+    end
+  end
+
+  def on_run_fibers(evt)
+    start_run
+    # run a Fiber for each worker
+    evt_id = evt.id
+    @workers = (0...WORKERS).collect do |worker|
+      # For each worker, start a new fiber in which the task runs
+      # Use a smaller time slice for each worker cycle, so as not to block the
+      # event loop too long, but increase cycles so the workers still get a decent
+      # amount of 'CPU' time running the simulated process.
+      Fiber.new do
+        # The long-running task
+        count = 0
+        (4*STEPS).times do | i |
+          # simulate processing step
+          count += Simulator.run(0.01) # give each processing cycle a maximum timeslice of 10 msec
+          # Communicate update
+          if evt_id == ID::RUN_FIBER_YIELD
+            Fiber.yield [worker, (i+1)/4]
           else
-            frame.call_after(:update_gauge, gauge_ix, i+1)
+            update_gauge(worker, (i+1)/4)
+            Fiber.yield
           end
         end
+        count
       end
-      @gauges << gauge
-      sizer.add(gauge, 0, Wx::GROW|Wx::ALL, 2)
     end
-    panel.sizer = sizer
-    sizer.fit(panel)
+  end
+
+  def on_run_ractor_threads(_)
+    start_run
+    # run a Ractor for each worker
+    @workers = (0...WORKERS).collect do |worker|
+      # for each worker start a Ractor to run the task
+      if RUBY_VERSION >= '4.0.0'
+        pin = Ractor::Port.new
+        pmon = Ractor::Port.new
+        r = Ractor.new(worker, self.make_shared, pin) do |worker_id, evt_handler, pout|
+          # The long-running task
+          count = 0
+          STEPS.times do | i |
+            count += Simulator.run(0.1) # give each processing cycle a maximum timeslice of 100 msec
+            # Update the main GUI asynchronously
+            pout.send(i+1)
+            evt = Wx::RT::ThreadEvent.new
+            evt.set_int(worker_id)
+            evt_handler.queue_event(evt)
+          end
+          pout.send(-1)
+          evt = Wx::RT::ThreadEvent.new
+          evt.set_int(worker_id)
+          evt_handler.queue_event(evt)
+          count
+        end
+        r.monitor(pmon)
+        [r, pin, pmon]
+      else
+        r = Ractor.new(worker, self.make_shared) do |worker_id, evt_handler|
+          # The long-running task
+          count = 0
+          STEPS.times do | i |
+            # simulate processing step
+            count += Simulator.run(0.1) # give each processing cycle a maximum timeslice of 100 msec
+            # Update the main GUI asynchronously
+            evt = Wx::RT::ThreadEvent.new
+            evt.set_int(worker_id)
+            evt_handler.queue_event(evt)
+            Ractor.yield(i+1)
+          end
+          evt = Wx::RT::ThreadEvent.new
+          evt.set_int(worker_id)
+          evt_handler.queue_event(evt)
+          Ractor.yield(-1)
+          count
+        end
+        [r]
+      end
+    end
+  end
+
+  def on_thread_event(evt)
+    w = evt.get_int
+    if RUBY_VERSION >= '4.0.0'
+      step = @workers[w][1].receive
+      if step >= 0
+        update_gauge(w, step)
+      else
+        rc = @workers[w][2].receive
+        Wx.message_box("Worker ##{w} aborted with error.", 'Worker Error',
+                       Wx::OK|Wx::CENTRE|Wx::ICON_ERROR, self) if rc == :aborted
+        @workers[w] << :stopped
+      end
+    else
+      step = begin; @workers[w][0].take; rescue Ractor::ClosedError; nil; end
+      if step && step >= 0
+        update_gauge(w, step)
+      else
+        @workers[w] << :stopped
+      end
+    end
+  end
+
+  def reset_gauges
+    WORKERS.times { |w| update_gauge(w, 0) }
   end
 
   def update_gauge(gauge_ix, value)
@@ -96,17 +296,77 @@ class ProgressFrame < Wx::Frame
   def on_progress_update(evt)
     update_gauge(evt.gauge, evt.value)
   end
+
+  def on_idle(evt)
+    unless @workers.empty?
+      case @workers.first
+      when ::Thread
+        if @workers.any? { |worker| worker.alive? }
+          if @queue
+            WORKERS.times do
+              data = @queue.shift(true) rescue nil
+              update_gauge(*data) if data
+              break unless data
+            end
+          end
+        else
+          @total = @workers.sum { |w| w.value }
+          @workers.clear
+          if @queue
+            begin
+              data = @queue.shift(true) rescue nil
+              update_gauge(*data) if data
+            end while data
+          else
+            Wx.get_app.yield
+          end
+          end_run(@total)
+        end
+      when ::Fiber
+        if @workers.any? { |worker| worker.alive? }
+          @workers.each do |fbr|
+            if fbr.alive?
+              data = fbr.resume rescue nil
+              if data
+                if ::Array === data
+                  update_gauge(*data)
+                else
+                  @total += data
+                end
+              end
+            end
+          end
+          evt.request_more # make sure we get another idle event to provide time slices for the fibers
+        else
+          end_run(@total)
+        end
+      else
+        if @workers.all? { |worker| worker.last == :stopped }
+          @total = @workers.sum { |w| w[0].value }
+          @workers.clear
+          end_run(@total)
+        end
+      end
+      evt.skip
+    end
+  end
+
+  def on_quit(_)
+    close(true)
+  end
+
+  def on_about(_)
+    msg =  sprintf("This is the About dialog of the threaded sample.\n" \
+                     "Welcome to wxRuby, version %s", Wx::WXRUBY_VERSION)
+    Wx::message_box(msg, "About Threaded", Wx::OK|Wx::ICON_INFORMATION, self)
+  end
+
 end
 
 # This app class creates a frame, and, importantly, a timer to allow
 # the threads some computing time
 class GaugeApp < Wx::App
   def on_init
-    # Create a global application timer that passes control to other
-    # ruby threads. The timer will run every 1/40 second (25ms). Higher
-    # values will make the other threads run more often, but will
-    # eventually degrade the responsiveness of the GUI.
-    Wx::Timer.every(25) { Thread.pass }
     prog = ProgressFrame.new
     prog.show
   end
@@ -122,22 +382,15 @@ module ThreadSample
     { file: __FILE__,
       summary: 'wxRuby threading example.',
       description: <<~__TXT
-        wxRuby example demonstrating how to use ruby threads in wxRuby.
-        This simple sample demonstrates how to use Ruby (green) threads
-        to execute non-GUI code in parallel with a wxRuby
+        wxRuby example demonstrating how to use concurrency in wxRuby.
+        This sample demonstrates how to use Ruby (green) threads, fibers 
+        and Ractor threads to execute non-GUI code in concurrently with a wxRuby
         GUI. This strategy is useful in a number of situations:
         
         * To keep the GUI responsive whilst computationally intensive
           operations are carried out in the background
         * To keep the GUI responsive while waiting for networking operations
           to complete 
-        
-        The basic problem is that, as with other Ruby GUI toolkits, non-GUI
-        threads will not, by default, get allocated time to run while Ruby is
-        busy in Wx code - the main wxRuby event loop. Strategies to deal with
-        this include using non-blocking IO, and, more generically, using
-        wxRuby's Timer class to explicitly allocate time for non-GUI threads
-        to run. The latter technique is shown here.
         __TXT
     }
   end

data/samples/help/doc/cshelp.txt

@@ -0,0 +1,9 @@
+.topic IDH_PANEL
+This is the topic for the main panel.
+
+.topic IDH_TEXT
+This is the topic for the text control.
+
+.topic IDH_OK
+This is the topic for the OK button.
+

data/samples/help/doc/doc.cnt

@@ -0,0 +1,8 @@
+:Base doc.hlp
+1 Introduction
+2 Introduction=intro
+2 Classes=classes
+2 Functions=functions
+2 About=about
+1 Chapter 2
+2 Chapter 2=chapter2

data/samples/help/doc/doc.h

@@ -0,0 +1,7 @@
+#define doc1       100
+#define doc2       2
+#define doc3       1
+#define doc4       3
+#define IDH_PANEL  300
+#define IDH_TEXT   301
+#define IDH_OK     302

data/samples/help/doc/doc.hhc

@@ -0,0 +1,40 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<HTML>
+<HEAD>
+<meta name="GENERATOR" content="tex2rtf">
+<!-- Sitemap 1.0 -->
+</HEAD><BODY>
+<OBJECT type="text/site properties">
+ <param name="ImageType" value="Folder">
+</OBJECT>
+<UL>
+<LI> <OBJECT type="text/sitemap">
+<param name="Local" value="doc.htm">
+<param name="Name" value="Contents">
+<param name="ID" value=0>
+</OBJECT>
+ <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc1.htm#intro">
+  <param name="Name" value="Introduction">
+  </OBJECT>
+<UL> <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc2.htm#classes">
+  <param name="Name" value="Classes">
+  <param name="ID" value=2>
+  </OBJECT>
+ <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc3.htm#functions">
+  <param name="Name" value="Functions">
+  <param name="ID" value=1>
+  </OBJECT>
+ <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc4.htm#about">
+  <param name="Name" value="About">
+  <param name="ID" value=3>
+  </OBJECT>
+</UL> <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc5.htm#chapter2">
+  <param name="Name" value="Chapter 2">
+  <param name="ID" value=4>
+  </OBJECT>
+</UL>

data/samples/help/doc/doc.hhk

@@ -0,0 +1,31 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<HTML>
+<HEAD>
+<meta name="GENERATOR" content="tex2rtf">
+<!-- Sitemap 1.0 -->
+</HEAD><BODY>
+<OBJECT type="text/site properties">
+ <param name="ImageType" value="Folder">
+</OBJECT>
+<UL>
+ <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc4.htm#about">
+  <param name="Name" value="About">
+  </OBJECT>
+ <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc1.htm#intro">
+  <param name="Name" value="Introduction">
+  </OBJECT>
+ <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc2.htm#classes">
+  <param name="Name" value="Classes">
+  </OBJECT>
+ <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc5.htm#chapter2">
+  <param name="Name" value="Chapter 2">
+  </OBJECT>
+ <LI> <OBJECT type="text/sitemap">
+  <param name="Local" value="doc3.htm#functions">
+  <param name="Name" value="Functions">
+  </OBJECT>
+</UL>