snow-data 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 425085a25eb678abb07c07ba25d1a52142d86822
-  data.tar.gz: b04d708b4f18e405354bd56f7175e4ddaec4291e
+  metadata.gz: de5502dc1786af224a1344f0221110e87bae22a0
+  data.tar.gz: 207bffe6bbe3d1bf6f6ff3bef67615b12ef3767d
 SHA512:
-  metadata.gz: f03aa50d5ad415403388c91d3560b0c3ca188ef8309797c3f3e6f342380c4880b37e224dd025870fa420ec8819b8d7d8a68e0e7aea13d63ab16b150b1228a846
-  data.tar.gz: 17975205c4c120f24ebd00ebe0feb6d47699847a063564a51e42f6a9b66a50d95a4b1ceb6414081bfe79620f6f9dd7ef235a37745db6616a84f738cb0caa1629
+  metadata.gz: c38b07ce23e8fc20c451c5d529d535e9bbe826a5e41f149d5903c29a53ac7d01024d0becda54c7e75e4c24e07f1b216fe4a87a45098394b121eb3de309bd860f
+  data.tar.gz: a71c448abd01932b31ec66d5bb197469b6b6521404fa270f20a45ae150eb51d798011e1fe56daea4d1421d684cf145c333582ecd6aa1d1db523f1bca01a5b5b6

data/ext/extconf.rb

@@ -19,6 +19,7 @@ option_mappings = {
   '-Ws'                  => OptKVPair[:warn_implicit_size, true],
   '--warn-no-bytesize'   => OptKVPair[:warn_no_bytesize, true],
   '-Wbs'                 => OptKVPair[:warn_implicit_size, true],
+  '--allow-alloca'       => OptKVPair[:allow_alloca, true],
   '--debug-memory-copy'  => OptKVPair[:debug_memory_copy, true],
   '--debug-allocations'  => OptKVPair[:debug_allocations, true]
 }
@@ -27,6 +28,7 @@ options = {
   :build_debug        => false,
   :warn_implicit_size => false,
   :warn_no_bytesize   => false,
+  :allow_alloca       => false,
   :debug_memory_copy  => false,
   :debug_allocations  => false
 }
@@ -50,6 +52,7 @@ else
   $stdout.puts "Building extension in release mode"
 end
 
+$CFLAGS += ' -DSD_ALLOW_ALLOCA' if options[:allow_alloca]
 $CFLAGS += ' -DSD_SD_WARN_ON_IMPLICIT_COPY_SIZE' if options[:warn_implicit_size]
 $CFLAGS += ' -DSD_WARN_ON_NO_BYTESIZE_METHOD' if options[:warn_no_bytesize]
 $CFLAGS += ' -DSD_VERBOSE_COPY_LOG' if options[:debug_memory_copy]

data/ext/snow-data/snow-data.c

@@ -8,6 +8,11 @@
 #include <stdint.h>
 #include <stdio.h>
 
+typedef enum e_sd_free_memory_flag {
+  SD_DO_NOT_FREE_MEMORY = 0,
+  SD_FREE_MEMORY        = 1
+} sd_free_memory_flag_t;
+
 static ID kSD_IVAR_BYTESIZE;
 static ID kSD_IVAR_ALIGNMENT;
 static ID kSD_ID_BYTESIZE;
@@ -175,33 +180,54 @@ static void *align_ptr(void *ptr, size_t alignment)
 /*
   Allocated a block of memory of at least size bytes aligned to the given byte
   alignment.
+
+  Raises a NoMemoryError if it's not possible to allocate memory.
  */
 static void *com_malloc(size_t size, size_t alignment)
 {
   const size_t aligned_size = align_size(size + sizeof(void *), alignment);
   void *const ptr = xcalloc(aligned_size, 1);
-  void **const aligned_ptr = align_ptr((uint8_t *)ptr + sizeof(void *), alignment);
+  void **aligned_ptr;
+
+  if (!ptr) {
+    rb_raise(rb_eNoMemError,
+      "Failed to allocate %zu (req: %zu) bytes via malloc",
+      aligned_size, size);
+    return NULL;
+  }
+
+  aligned_ptr = align_ptr((uint8_t *)ptr + sizeof(void *), alignment);
   aligned_ptr[-1] = ptr;
+
   #ifdef SD_VERBOSE_MALLOC_LOG
   fprintf(stderr, "Allocated block %p with aligned size %zu (requested: %zu"
     " aligned to %zu bytes), returning aligned pointer %p with usable size %td\n",
     ptr, aligned_size, size, alignment, aligned_ptr,
     (uint8_t *)(ptr + aligned_size) - (uint8_t *)aligned_ptr);
   #endif
+
   return aligned_ptr;
 }
 
 /*
   Frees memory previously allocated by com_malloc. This _does not work_ if it
   was allocated by any other means.
+
+  Raises a RuntimeError if aligned_ptr is NULL.
  */
 static void com_free(void *aligned_ptr)
 {
+  if (!aligned_ptr) {
+    rb_raise(rb_eRuntimeError, "Attempt to call free on NULL");
+    return;
+  }
+
   #ifdef SD_VERBOSE_MALLOC_LOG
   fprintf(stderr, "Deallocating aligned pointer %p with underlying pointer %p\n",
     aligned_ptr,
     ((void **)aligned_ptr)[-1]);
   #endif
+
   xfree(((void **)aligned_ptr)[-1]);
 }
 
@@ -1286,9 +1312,44 @@ static VALUE sd_set_string(int argc, VALUE *argv, VALUE self)
   return sd_set_string_nullterm(self, sd_offset, sd_value, !!RTEST(sd_null_terminated));
 }
 
+/*
+  Frees memory associated with self regardless of whether the object is frozen.
+ */
+static void sd_memory_force_free(VALUE self)
+{
+  struct RData *data = RDATA(self);
+
+  if (data->data && data->dfree) {
+    data->dfree(data->data);
+    data->dfree = 0;
+  } else if (!data->data) {
+    rb_raise(rb_eRuntimeError,
+      "Double-free on %s",
+      rb_obj_classname(self));
+  }
+
+  data->data = 0;
+  rb_ivar_set(self, kSD_IVAR_BYTESIZE, INT2FIX(0));
+}
+
+/*
+  Returns a Data object wrapped with the given klass and the appropriate size
+  and alignment instance variables.
+ */
+static VALUE sd_wrap_memory(VALUE klass, void *data, size_t size, size_t alignment, sd_free_memory_flag_t should_free)
+{
+  VALUE memory = Data_Wrap_Struct(klass, 0, (should_free ? com_free : 0), data);
+  rb_ivar_set(memory, kSD_IVAR_BYTESIZE, SIZET2NUM(size));
+  rb_ivar_set(memory, kSD_IVAR_ALIGNMENT, SIZET2NUM(alignment));
+  rb_obj_call_init(memory, 0, 0);
+  return memory;
+}
+
 /*
   call-seq:
       new(address, size, alignment = SIZEOF_VOID_POINTER) => Memory
+      wrap(address, size, alignment = SIZEOF_VOID_POINTER) => Memory
+      __wrap__(address, size, alignment = SIZEOF_VOID_POINTER) => Memory
 
   Creates a new Memory object that wraps an existing pointer. Alignment is
   optional and defaults to the size of a pointer (Memory::SIZEOF_VOID_POINTER).
@@ -1310,7 +1371,7 @@ static VALUE sd_set_string(int argc, VALUE *argv, VALUE self)
   an ArgumentError to provide a NULL (zero) address.
 
   If a subclass overrides ::new, it is also aliased as ::wrap and ::__wrap__.
-  Subclasses may override ::wrap but must not override ::__wrap__.
+  Subclasses may override ::wrap or ::new but must never override ::__wrap__.
  */
 static VALUE sd_memory_new(int argc, VALUE *argv, VALUE self)
 {
@@ -1346,11 +1407,7 @@ static VALUE sd_memory_new(int argc, VALUE *argv, VALUE self)
     alignment = NUM2SIZET(sd_alignment);
   }
 
-  memory = Data_Wrap_Struct(self, 0, 0, address);
-  rb_ivar_set(memory, kSD_IVAR_BYTESIZE, SIZET2NUM(size));
-  rb_ivar_set(memory, kSD_IVAR_ALIGNMENT, SIZET2NUM(alignment));
-  rb_obj_call_init(memory, 0, 0);
-  rb_obj_taint(memory);
+  memory = sd_wrap_memory(self, address, size, alignment, SD_DO_NOT_FREE_MEMORY);
 
   return memory;
 }
@@ -1358,11 +1415,16 @@ static VALUE sd_memory_new(int argc, VALUE *argv, VALUE self)
 /*
   call-seq:
       malloc(size, alignment = nil) => Memory
+      __malloc__(size, alignment = nil) => Memory
 
   Allocates a new block with the given size and alignment and returns it. If
   no alignment is specified, it defaults to Snow::Memory::SIZEOF_VOID_POINTER.
 
   Raises a RangeError if either size is zero or alignment is not a power of two.
+
+  If a subclass overrides ::malloc, which is a bad idea and should not be done,
+  then it is aliased as ::__malloc__ as well. Subclasses must never override
+  ::__malloc__.
  */
 static VALUE sd_memory_malloc(int argc, VALUE *argv, VALUE self)
 {
@@ -1388,15 +1450,82 @@ static VALUE sd_memory_malloc(int argc, VALUE *argv, VALUE self)
 
   /* Allocate block */
   data = com_malloc(size, alignment);
-  memory  = Data_Wrap_Struct(self, 0, com_free, data);
+  memory = sd_wrap_memory(self, data, size, alignment, SD_FREE_MEMORY);
 
-  rb_ivar_set(memory, kSD_IVAR_BYTESIZE, SIZET2NUM(size));
-  rb_ivar_set(memory, kSD_IVAR_ALIGNMENT, SIZET2NUM(alignment));
-  rb_obj_call_init(memory, 0, 0);
-  rb_obj_taint(memory);
   return memory;
 }
 
+#ifdef SD_ALLOW_ALLOCA
+/*
+  call-seq:
+      alloca(size) { |memory| ... } => result of block
+      __alloca__(size) { |memory| ... } => result of block
+
+  Allocates size bytes on the stack and yields it to a block before for use,
+  then returns the result of the block. Outside of the block, any use of the
+  yielded memory's address is considered undefined behavior and may lead to
+  crashes or worse. The yielded memory is only valid for the duration of the
+  block. If you want to preserve the memory after use, either duplicate the
+  memory block or realloc! the memory, both of which will copy it from the stack
+  to the heap.
+
+  The alignment of the yielded memory is always the size of a pointer.
+
+  Because of how downright evil alloca is in some situations, it is disabled by
+  default. You must explicitly install snow-data with the --allow-alloca flag to
+  use this function. If you're not certain whether alloca is available for a
+  particular installation, then you should check if the Memory class responds to
+  it first.
+
+      if Snow::Memory.respond_to?(:__alloca__)
+        Snow::Memory.__alloca__(64) { |mem|
+          # ...
+        }
+      end
+
+  Subclasses may override alloca to provide a predefined size argument, but
+  subclasses must never override __alloca__. It is considered bad form to
+  implement __alloca__ using heap allocation for installations that don't
+  provide it.
+ */
+static VALUE sd_memory_alloca(VALUE self, VALUE sd_size)
+{
+  VALUE result = Qnil;
+  void *stack_memory = NULL;
+  struct RData *block_data;
+  size_t size = NUM2SIZET(sd_size);
+  VALUE block;
+
+  rb_need_block();
+
+  if (size == 0) {
+    rb_raise(rb_eRangeError, "Size of block must be 1 or more -- zero-byte"
+      " blocks are not permitted.");
+  }
+
+  stack_memory = alloca(size);
+  if (stack_memory == NULL) {
+    rb_raise(rb_eNoMemError,
+      "Failed to allocated %zu bytes via alloca",
+      size);
+  }
+
+  block = sd_wrap_memory(self, stack_memory, size, SIZEOF_VOIDP, SD_DO_NOT_FREE_MEMORY);
+  block_data = RDATA(block);
+  result = rb_yield(block);
+
+  /*
+    If the block hasn't been realloc!'d or freed, free it now if it hasn't been
+    frozen for some reason.
+   */
+  if (block_data->data == stack_memory && !block_data->dfree && !OBJ_FROZEN(block)) {
+    sd_memory_force_free(block);
+  }
+
+  return result;
+}
+#endif
+
 /*
   call-seq:
       realloc!(size, alignment = nil) => self
@@ -1488,22 +1617,8 @@ static VALUE sd_memory_realloc(int argc, VALUE *argv, VALUE self)
  */
 static VALUE sd_memory_free(VALUE self)
 {
-  struct RData *data = RDATA(self);
-
   rb_check_frozen(self);
-
-  if (data->data && data->dfree) {
-    data->dfree(data->data);
-    data->dfree = 0;
-  } else if (!data->data) {
-    rb_raise(rb_eRuntimeError,
-      "Double-free on %s",
-      rb_obj_classname(self));
-  }
-
-  data->data = 0;
-  rb_ivar_set(self, kSD_IVAR_BYTESIZE, INT2FIX(0));
-
+  sd_memory_force_free(self);
   return self;
 }
 
@@ -1804,8 +1919,11 @@ void Init_snowdata_bindings(void)
   rb_const_set(sd_memory_klass, rb_intern("SIZEOF_UINTPTR_T"), SIZET2NUM(SIZEOF_UINTPTR_T));
   rb_const_set(sd_memory_klass, rb_intern("SIZEOF_VOID_POINTER"), SIZET2NUM(sizeof(void *)));
 
-  rb_define_singleton_method(sd_memory_klass, "new", sd_memory_new, -1);
-  rb_define_singleton_method(sd_memory_klass, "malloc", sd_memory_malloc, -1);
+  rb_define_singleton_method(sd_memory_klass, "__wrap__", sd_memory_new, -1);
+  rb_define_singleton_method(sd_memory_klass, "__malloc__", sd_memory_malloc, -1);
+  #ifdef SD_ALLOW_ALLOCA
+  rb_define_singleton_method(sd_memory_klass, "__alloca__", sd_memory_alloca, 1);
+  #endif
   rb_define_singleton_method(sd_memory_klass, "align_size", sd_align_size, -1);
   rb_define_method(sd_memory_klass, "realloc!", sd_memory_realloc, -1);
   rb_define_method(sd_memory_klass, "copy!", sd_memory_copy, -1);

data/lib/snow-data/c_struct.rb

@@ -4,6 +4,8 @@
 
 require 'snow-data/snowdata_bindings'
 require 'snow-data/memory'
+require 'snow-data/c_struct/struct_base'
+require 'snow-data/c_struct/array_base'
 
 module Snow
 
@@ -17,186 +19,42 @@ class CStruct
   StructMemberInfo = Struct.new(:name, :type, :size, :length, :alignment, :offset)
 
 
-
   #
-  # Struct base class. Not to be used directly, as it does not provide all the
-  # constants and methods necessary for a struct.
+  # Whether long inspect strings are enabled. See both ::long_inspect= and
+  # ::long_inspect for accessors.
   #
-  class StructBase < ::Snow::Memory
-
-    @@long_inspect = false
-
-    #
-    # Whether long inspect strings are enabled. By default, they are disabled.
-    #
-    # Long inspect strings can be useful for debugging, sepcially if you want to
-    # see the value, length, and alignment of every struct member in inspect
-    # strings. Otherwise, you can safely leave this disabled.
-    #
-    def self.long_inspect=(enabled)
-      @@long_inspect = !!enabled
-    end
-
-
-    def self.long_inspect
-      @@long_inspect
-    end
-
-
-    #
-    # Returns the offset of a member.
-    #
-    def self.offset_of(member)
-      self.MEMBERS_HASH[member].offset
-    end
-
-
-    #
-    # Returns the type name of a member.
-    #
-    def self.type_of(member)
-      self.MEMBERS_HASH[member].type
-    end
-
-
-    #
-    # Returns the size in bytes of a member.
-    #
-    def self.bytesize_of(member)
-      self.MEMBERS_HASH[member].size
-    end
-
-
-    #
-    # Returns the alignment of a member.
-    #
-    def self.alignment_of(member)
-      self.MEMBERS_HASH[member].alignment
-    end
-
-
-    #
-    # Returns the length of a member.
-    #
-    def self.length_of(member)
-      self.MEMBERS_HASH[member].length
-    end
-
-
-
-    #
-    # Returns the address of a member. This address is only valid for the
-    # receiver.
-    #
-    def address_of(member)
-      self.address + self.class.offset_of(member)
-    end
-
-
-    #
-    # Returns the offset of a member.
-    #
-    def offset_of(member)
-      self.class.offset_of(member)
-    end
-
-
-    #
-    # Returns the size in bytes of a member.
-    #
-    def bytesize_of(member)
-      self.class.bytesize_of(member)
-    end
-
-
-    #
-    # Returns the alignment of a member.
-    #
-    def alignment_of(member)
-      self.class.alignment_of(member)
-    end
-
-
-    #
-    # Returns the length of a member.
-    #
-    def length_of(member)
-      self.class.length_of(member)
-    end
-
-
-    #
-    # Returns the type name of a member.
-    #
-    def type_of(member)
-      self.class.type_of(member)
-    end
-
-
-    #
-    # Returns a hash of all of the struct's member names to their values.
-    #
-    def to_h
-      self.class::MEMBERS.inject({}) do |hash, member|
-        length = member.length
-        name   = member.name
-
-        hash[name] = if length > 1
-          (0 ... length).map { |index| __send__(name, index) }
-        else
-          __send__(name)
-        end
-
-        hash
-      end
-    end
+  @@long_inspect = false
 
 
-    #
-    # Returns a string describing the struct, including its classname, object
-    # ID, address, size, and alignment. In addition, if long_inspect is enabled,
-    # then it will also include the values of the struct's members.
-    #
-    def inspect
-      id_text     = __id__.to_s(16).rjust(14, ?0)
-      addr_text   = self.address.to_s(16).rjust(14, ?0)
-
-      member_text = if ! null? && self.class.long_inspect
-        # Get member text
-        all_members_text = (self.class::MEMBERS.map do |member|
-          name        = member.name
-          type        = member.type
-          align       = member.alignment
-          length      = member.length
-          length_decl = length > 1 ? "[#{length}]" : ''
-
-          values_text = if length > 1
-            single_member_text = (0 ... length).map { |index|
-                "[#{ index }]=#{ self.__send__(member.name, index).inspect }"
-              }.join(', ')
-
-              "{ #{ single_member_text } }"
-            else
-              self.__send__(member.name).inspect
-            end
-
-          "#{ name }:#{ type }#{ length_decl }:#{ align }=#{ values_text }"
-
-        end).join('; ')
-
-        " #{all_members_text}"
-      else # member_text = if ...
-        # Skip members
-        ''
-      end # member_text = if ...
-
-      "<#{ self.class }:0x#{ id_text } *0x#{ addr_text }:#{ self.bytesize }:#{ self.alignment }#{member_text}>"
-    end
+  #
+  # call-seq:
+  #     long_inspect = boolean => boolean
+  #
+  # Sets whether long inspect strings are enabled. By default, they are disabled.
+  #
+  # Long inspect strings can be useful for debugging, sepcially if you want to
+  # see the value, length, and alignment of every struct member in inspect
+  # strings. Otherwise, you can safely leave this disabled.
+  #
+  def self.long_inspect=(enabled)
+    @@long_inspect = !!enabled
+  end
 
 
-  end # class StructBase
+  #
+  # call-seq:
+  #     long_inspect => boolean
+  #
+  # Returns whether long_inspect is enabled. By default, it is disabled.
+  #
+  def self.long_inspect
+    @@long_inspect
+  end
 
 
+  #
+  # call-seq:
+  #     power_of_two?(num) => boolean
   #
   # Returns whether num is a power of two and nonzero.
   #
@@ -205,6 +63,9 @@ class CStruct
   end
 
 
+  #
+  # call-seq:
+  #     member_encoding(name, type, length: 1, alignment: nil) => String
   #
   # Returns an encoding for a struct member with the given name, type,
   # length, and alignment. The type must be a string or symbol, not a Class or
@@ -228,6 +89,9 @@ class CStruct
   #--
   # Ordinarily I'd write a lexer for this sort of thing, but regex actually
   # seems to work fine.
+  #
+  # TODO: At any rate, replace this with a lexer/parser. At least that way it'll
+  # be possible to provide validation for encodings.
   #++
   ENCODING_REGEX = %r{
       (?<name>                                      # 0
@@ -247,6 +111,7 @@ class CStruct
     \s* (?: ; | $ | \n) # terminator
   }mx
 
+
   # Alignemnts for default types.
   ALIGNMENTS = {
     :char                 => 1,
@@ -276,6 +141,7 @@ class CStruct
     :uintptr_t            => Memory::SIZEOF_UINTPTR_T
   }
 
+
   # Sizes of default types.
   SIZES = {
     :char                 => 1,
@@ -305,6 +171,7 @@ class CStruct
     :uintptr_t            => Memory::SIZEOF_UINTPTR_T
   }
 
+
   # Used for getters/setters on Memory objects. Simply maps short type names to
   # their long-form type names.
   LONG_NAMES = {
@@ -488,233 +355,140 @@ class CStruct
   # `fetch(index)` and `store(index, value)` methods, both aliased to `[]` and
   # `[]=` respectively.
   #
-  def self.new(*args)
-    encoding, klass_name = case args.length
-    when 1 then args
-    when 2 then args.reverse
-    else
-      raise ArgumentError, "Invalid arguments to CStruct::new"
-    end
-
+  def self.new(klass_name = nil, encoding)
     klass_name = klass_name.intern if klass_name
 
-    members = []
-
-    encoding.scan(ENCODING_REGEX) do
-      |match|
-      name   = match[0].intern
-      type   = match[1].intern
-      type = LONG_NAMES[type] if LONG_NAMES.include?(type)
-      length = (match[3] || 1).to_i
-      align  = (match[5] || ALIGNMENTS[type] || 1).to_i
-      offset = 0
-
-      last_type = members.last
-      if last_type
-        offset += Memory.align_size(last_type.offset + last_type.size, align)
-      end
-
-      members << StructMemberInfo[name, type, SIZES[type] * length, length, align, offset].freeze
-    end
+    members = decode_member_info(encoding)
 
     raise "No valid members found in encoding" if members.empty?
 
-    alignment = members.map { |member| member.alignment }.max { |lhs, rhs| lhs <=> rhs }
-    size = members.last.size + members.last.offset
-    aligned_size = Memory.align_size(size, alignment)
-
-    members.freeze
-
-    klass = Class.new(StructBase) do |struct_klass|
-      const_set(:ENCODING,      String.new(encoding).freeze)
-      const_set(:MEMBERS,       members)
-      const_set(:SIZE,          size)
-      const_set(:ALIGNED_SIZE,  aligned_size)
-      const_set(:ALIGNMENT,     alignment)
-      const_set(:MEMBERS_HASH,  members.reduce({}) { |offs, member| offs[member.name] = member ; offs })
-
-      def self.new(&block)
-        inst = __malloc__(self::SIZE, self::ALIGNMENT)
-        yield(inst) if block_given?
-        inst
-      end
-
-      self::MEMBERS.each do
-        |member|
-
-        name        = member.name
-        index_range = (0...member.length)
-        type_name   = member.type
-        type_size   = ::Snow::CStruct::SIZES[member.type]
-        offset      = member.offset
-        getter      = :"get_#{type_name}"
-        setter      = :"set_#{type_name}"
-        get_name    = :"get_#{name}"
-        set_name    = :"set_#{name}"
-
-        define_method(get_name) do |index = 0|
-          if index === index_range
-            raise RangeError, "Index #{index} for #{name} is out of range: must be in #{index_range}"
-          end
-          off = offset + index * type_size
-          __send__(getter, off)
-        end # get_name
-
-
-        define_method(set_name) do |value, index = 0|
-          if index === index_range
-            raise RangeError, "Index #{index} for #{name} is out of range: must be in #{index_range}"
-          end
-          off = offset + index * type_size
-          __send__(setter, off, value)
-          value
-        end # set_name
-
-
-        alias_method :"#{name}", get_name
-        alias_method :"#{name}=", set_name
-
-      end # define member get / set methods
-
-
-      # Array inner class (not a subclass of StructBase because it has no members itself)
-      const_set(:Array, Class.new(Memory) do |array_klass|
-
-        const_set(:BASE, struct_klass)
-
-        # The length of the array.
-        attr_reader :length
-
-
-        include Enumerable
-
-
-        def self.wrap(address, length_in_elements) # :nodoc:
-          __wrap__(address, length_in_elements * self::BASE::SIZE)
-        end
-
-
-        def self.new(length) # :nodoc:
-          length = length.to_i
-          raise ArgumentError, "Length must be greater than zero" if length < 1
-          inst = __malloc__(length * self::BASE::SIZE, self::BASE::ALIGNMENT)
-          inst.instance_variable_set(:@length, length)
-          inst.instance_variable_set(:@__cache__, nil)
-          inst
-        end
-
-
-        def resize!(new_length) # :nodoc:
-          raise ArgumentError, "Length must be greater than zero" if new_length < 1
-          realloc!(new_length * self.class::BASE::SIZE, self.class::BASE::ALIGNMENT)
-          @length = new_length
-          __free_cache__
-          self
-        end
-
-
-        def each(&block) # :nodoc:
-          return to_enum(:each) unless block_given?
-          (0 ... self.length).each { |index| yield fetch(index) }
-          self
-        end
+    klass = build_struct_type(members)
 
+    if klass_name
+      const_set(klass_name, klass)
+      add_type(klass_name, klass)
+    end
 
-        def map(&block) # :nodoc:
-          return to_enum(:map) unless block_given?
-          self.dup.map!(&block)
-        end
+    klass
+  end
 
 
-        def map!(&block) # :nodoc:
-          return to_enum(:map!) unless block_given?
-          (0 ... self.length).each { |index| store(index, yield(fetch(index))) }
-          self
-        end
+  #
+  # Decodes an encoding string and returns an array of StructMemberInfo objects
+  # describing the members of a struct for the given encoding. You may then pass
+  # this array to build_struct_type to create a new struct class or
+  # encode_member_info to get an encoding string for the encoding string you
+  # just decoded, as though that were useful to you somehow.
+  #
+  def self.decode_member_info(encoding)
+    total_size = 0
+    encoding.scan(ENCODING_REGEX).map do
+      |match|
+      name        = match[0].intern
+      type        = match[1].intern
+      type        = LONG_NAMES[type] if LONG_NAMES.include?(type)
+      length      = (match[3] || 1).to_i
+      align       = (match[5] || ALIGNMENTS[type] || 1).to_i
+      size        = SIZES[type] * length
+      offset      = Memory.align_size(total_size, align)
+      total_size  = offset + size
+
+      StructMemberInfo[name, type, size, length, align, offset]
+    end
+  end
 
 
-        def to_a # :nodoc:
-          (0 ... self.length).map { |index| fetch(index) }
-        end
+  #
+  # Given an array of StructMemberInfo objects, returns a valid encoding string
+  # for those objects in the order they're specified in the array. The info
+  # objects' offsets are ignored, as these cannot be specified using an encoding
+  # string.
+  #
+  def self.encode_member_info(members)
+    members.map { |member|
+      "#{member.name}:#{member.type}[#{member.length}]:#{member.alignment}"
+    }.join(?;)
+  end
 
 
-        def fetch(index) # :nodoc:
-          raise RuntimeError, "Attempt to access deallocated array" if @length == 0
-          raise RangeError, "Attempt to access out-of-bounds index in #{self.class}" if index < 0 || @length <= index
-          __build_cache__ if ! @__cache__
-          @__cache__[index]
-        end
-        alias_method :[], :fetch
-
-
-        #
-        # You can use this to assign _any_ Data subclass to an array value, but
-        # keep in mind that the data assigned MUST -- again, MUST -- be at least
-        # as large as the array's base struct type in bytes or the assigned
-        # data object MUST respond to a bytesize message to get its size in
-        # bytes.
-        #
-        def store(index, data) # :nodoc:
-          raise RuntimeError, "Attempt to access deallocated array" if @length == 0
-          raise TypeError, "Invalid value type, must be Data, but got #{data.class}" if ! data.kind_of?(Data)
-          raise RangeError, "Attempt to access out-of-bounds index in #{self.class}" if index < 0 || @length <= index
-          @__cache__[index].copy!(data)
-          data
-        end
-        alias_method :[]=, :store
+  #
+  # call-seq:
+  #   build_struct_type(members) => Class
+  #
+  # Builds a struct type for the given array of StructMemberInfo objects. The
+  # array of member objects must not be empty.
+  #
+  def self.build_struct_type(members)
+    raise ArgumentError, "Members array must not be empty" if members.empty?
 
+    # Make a copy of the members array so we can store a frozen version of it
+    # in the new struct class.
+    members = Marshal.load(Marshal.dump(members))
+    members.map! { |info| info.freeze }
+    members.freeze
 
+    # Get the alignment, size, aligned size, and encoding of the struct.
+    alignment = members.map { |member| member.alignment }.max { |lhs, rhs| lhs <=> rhs }
+    size = members.last.size + members.last.offset
+    aligned_size = Memory.align_size(size, alignment)
+    # Oddly enough, it would be easier to pass the encoding string into this
+    # function, but then it would ruin the nice little thing I have going where
+    # this function isn't dependent on parsing encodings, so we reproduce the
+    # encoding here as though it wasn't sitting just above us in the stack
+    # (which it might not be, but the chance of it is slim to none).
+    encoding = encode_member_info(members).freeze
+
+    Class.new(Memory) do |struct_klass|
+      # Set the class's constants, then include StructBase to define its members
+      # and other methods.
+      const_set(:ENCODING,      encoding)
+      const_set(:MEMBERS,       members)
+      const_set(:SIZE,          size)
+      const_set(:ALIGNED_SIZE,  aligned_size)
+      const_set(:ALIGNMENT,     alignment)
 
-        def free! # :nodoc:
-          __free_cache__
-          @length = 0
-          super
-        end
+      const_set(:MEMBERS_HASH,  members.reduce({}) { |hash, member|
+        hash[member.name] = member
+        hash
+      })
 
+      const_set(:MEMBERS_GETFN, members.reduce({}) { |hash, member|
+        hash[member.name] = :"get_#{member.name}"
+        hash
+      })
 
-        private
+      const_set(:MEMBERS_SETFN, members.reduce({}) { |hash, member|
+        hash[member.name] = :"set_#{member.name}"
+        hash
+      })
 
-        def __free_cache__ # :nodoc:
-          if @__cache__
-            @__cache__.each { |entry|
-              entry.free!
-              entry.remove_instance_variable(:@__base_memory__)
-            } # zeroes address, making it NULL
-            @__cache__ = nil
-          end
-        end
 
+      private :realloc!
 
-        def __build_cache__ # :nodoc:
-          addr = self.address
-          @__cache__ = (0...length).map { |index|
-            wrapper = self.class::BASE.__wrap__(addr + index * self.class::BASE::SIZE, self.class::BASE::SIZE)
-            # Make sure the wrapped object keeps the memory from being collected while it's in use
-            wrapper.instance_variable_set(:@__base_memory__, self)
-            wrapper
-          }
-        end
+      include StructBase
 
+      # Build and define the struct type's array class.
+      const_set(:Array, CStruct.build_array_type(self))
+    end
 
-        class <<self # :nodoc: all
-          alias_method :[], :new
-        end
+  end
 
-      end)
 
-      def self.[](length) # :nodoc:
-        self::Array.new(length)
-      end
+  #
+  # :nodoc:
+  # Generates an array class for the given struct class. This is called by
+  # ::build_struct_type and so shouldn't be called manually.
+  #
+  def self.build_array_type(struct_klass)
+    Class.new(Memory) do |array_klass|
+      const_set(:BASE, struct_klass)
 
-    end
+      private :realloc!
 
-    if klass_name
-      const_set(klass_name, klass)
-      add_type(klass_name, klass)
-    end
+      include StructArrayBase
+    end # Class.new
+  end # build_array_type
 
-    klass
-  end
 
   class <<self ; alias_method :[], :new ; end