ndtypes 0.2.0dev4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1e4f279735d63cdb4899d3df98a78dcde783ea64
+  data.tar.gz: 48e2f95ae6030f6c333ffbf88d8b253f6950830b
+SHA512:
+  metadata.gz: 9f23ebcc82f55ddd54e2417a106e4ab0bf9804ee5c8e951e65f6366b4530bc60a6d0e1992ed5aad32d734ff709f62473e6ce6b9fe2a4ac8f4f8b6c7417fcf008
+  data.tar.gz: 5006d479c176243f23e9956a25890b0caf3df0b1cee7a1546fccc7f1e8b64dd6bfad3b8dddfa796146e9a296cbb32904fe850e84465a77ec9968bd748fec8402

data/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Developer notes
+
+## Interfacing with Ruby's GC
+
+### Background
+
+Ruby uses a mark-and-sweep GC that scans the entire Ruby interpreter stack for
+objects that have gone out of scope and can be freed from memory. It does not 
+offer any of the reference counting mechanism that the Python GC offers. 
+
+While both approaches have their pros and cons, in the context of the ndtypes 
+wrapper, it becomes risky to have 'internal' Ruby objects that are only visible
+to the C API and are shared between multiple user-facing Ruby objecs. If one of
+the user-facing objects goes out of scope there is a possibilty that the GC will
+clean up the internal object that is shared between multiple user-facing objects
+(some of which might still be in use) and that will lead to segfaults.
+
+To avoid such a situation, in ndtypes we use a 'global GC guard' (inspired by @mrkn's
+[pycall.rb](https://github.com/mrkn/pycall.rb) gem) that stores the reference to the internal objects in a global Hash
+so that they don't go out of scope. When a user-facing object needs to be freed, we remove
+the reference to the user-facing object and its corresponding internal object from the
+global Hash.
+
+### Details
+
+More concretely, the `NdtObject` struct houses a `VALUE` object called `rbuf`. The struct
+has the following definition:
+```
+typedef struct {
+  VALUE rbuf;                  /* resource buffer */
+  ndt_t *ndt;                   /* type */
+} NdtObject;
+```
+In the above, the `rbuf` is a Ruby object that contains a struct of type `ResourceBufferObject`.
+This is the internal object that need to be shared among multiple user-facing `NDTypes` objects.
+
+The `gc_guard.c` file contains functions that help us interface with a global hash called
+`__gc_guard_table` that is present under the `NDTypes::GCGuard` module as a instance variable 
+on the module object.
+
+### Impact on contributor
+
+Whenever you allocate an `NDTypes` object you call the `gc_guard_register` function and pass
+it the pointer of the `NdtObject` struct that you have allocated along with the `rbuf` object.
+
+When an `NDTypes` objects needs to be freed (for example by the GC using the `NDTypes_dfree`
+function), you must call the `gc_guard_unregister` function that will remove the reference
+to the `rbuf` object from the global Hash.
+
+Forgetting to call above procedures can lead to hard-to-trace GC errors.

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/README.md

@@ -0,0 +1,19 @@
+# ndtypes
+
+Ruby wrapper over the libndtypes library.
+
+# Installation
+
+Run `gem install ndtypes --pre` to install on your machine.
+
+# Usage
+
+
+
+# Tests
+
+Run `rspec`.
+
+# Contributing
+
+Read the `CONTRIBUTING.md` file to know how to contribute to NDTypes.

data/Rakefile

@@ -0,0 +1,125 @@
+require 'rake'
+require 'rake/extensiontask'
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+require 'fileutils'
+require "ndtypes/version.rb"
+
+gemspec = eval(IO.read("ndtypes.gemspec"))
+
+ext_name = "ruby_ndtypes"
+Rake::ExtensionTask.new(ext_name, gemspec) do |ext|
+  ext.ext_dir = "ext/#{ext_name}"
+  ext.source_pattern = "**/*.{c, h}"
+end
+
+def run *cmd
+  sh(cmd.join(" "))
+end
+
+BASEDIR = Pathname( __FILE__ ).dirname.relative_path_from( Pathname.pwd )
+SPECDIR = BASEDIR + 'spec'
+
+VALGRIND_OPTIONS = [
+    "--tool=memcheck",
+    #"--leak-check=yes",
+    "--num-callers=15",
+    #"--error-limit=no",
+    "--partial-loads-ok=yes",
+    "--undef-value-errors=no" #,
+    #"--dsymutil=yes"
+]
+
+CALLGRIND_OPTIONS = [
+    "--tool=callgrind",
+    "--dump-instr=yes",
+    "--simulate-cache=yes",
+    "--collect-jumps=yes"
+]
+
+VALGRIND_MEMORYFILL_OPTIONS = [
+    "--freelist-vol=100000000",
+    "--malloc-fill=6D",
+    "--free-fill=66 ",
+]
+
+GDB_OPTIONS = []
+
+namespace :spec do
+  # partial-loads-ok and undef-value-errors necessary to ignore
+  # spurious (and eminently ignorable) warnings from the ruby
+  # interpreter
+
+  RSPEC_CMD = [ 'ruby', '-S', 'rspec', '-Ilib:ext', SPECDIR.to_s ]
+
+  desc "Run specs under GDB."
+  task :gdb => [ :compile ] do |task|
+          cmd = [ 'gdb' ] + GDB_OPTIONS
+    cmd += [ '--args' ]
+    cmd += RSPEC_CMD
+    run( *cmd )
+  end
+
+  desc "Run specs under cgdb."
+  task :cgdb => [ :compile ] do |task|
+    cmd = [ 'cgdb' ] + GDB_OPTIONS
+    cmd += [ '--args' ]
+    cmd += RSPEC_CMD
+    run( *cmd )
+  end
+
+  desc "Run specs under Valgrind."
+  task :valgrind => [ :compile ] do |task|
+    cmd = [ 'valgrind' ] + VALGRIND_OPTIONS
+    cmd += RSPEC_CMD
+    run( *cmd )
+  end
+
+  desc "Run specs under Callgrind."
+  task :callgrind => [ :compile ] do |task|
+    cmd = [ 'valgrind' ] + CALLGRIND_OPTIONS
+    cmd += RSPEC_CMD
+    run( *cmd )
+  end
+end
+
+LEAKCHECK_CMD = [ 'ruby', '-Ilib:ext', "#{SPECDIR}/leakcheck.rb" ]
+
+desc "Run leakcheck script."
+task :leakcheck => [ :compile ] do |task|
+  cmd = [ 'valgrind' ] + VALGRIND_OPTIONS
+  cmd += LEAKCHECK_CMD
+  run( *cmd )
+end
+
+task :clobber do |task|
+  [
+    "ext/#{ext_name}/include",
+    "ext/#{ext_name}/share",
+    "ext/#{ext_name}/lib",
+  ].each do |f|
+    puts "deleting folder #{f}..."
+    FileUtils.rm_rf(f)
+  end
+
+  Dir.chdir("ext/#{ext_name}/ndtypes/libndtypes/") do
+    system("make clean")
+  end
+end
+
+task :deploy do |task|
+  ext_ndtypes = "ext/ruby_ndtypes/ndtypes"
+  puts "deleting previously created #{ext_ndtypes} directory..."
+  FileUtils.rm_rf(ext_ndtypes)
+  Dir.mkdir(ext_ndtypes)
+
+  puts "cloning ndtypes repo into ext/ folder..."
+  system("git clone https://github.com/plures/ndtypes #{ext_ndtypes}")
+
+  Dir.chdir(ext_ndtypes) do
+    system("git checkout #{NDTypes::COMMIT}")
+  end
+
+  puts "building gem with rake build..."
+  system("rake build")
+end

data/ext/ruby_ndtypes/extconf.rb

@@ -0,0 +1,55 @@
+require 'mkmf'
+
+def windows?
+  (/cygwin|mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM) != nil
+end
+
+def mac?
+  (/darwin/ =~ RUBY_PLATFORM) != nil
+end
+
+def unix?
+  !windows?
+end
+
+puts "compiling libndtypes on your machine..."
+Dir.chdir(File.join(File.dirname(__FILE__) + "/ndtypes")) do
+  if unix?
+    ["libndtypes", "libndtypes/compat", "libndtypes/serialize"].each do |f|
+      Dir.chdir(f) do
+        Dir.mkdir(".objs") unless Dir.exists? ".objs"  
+      end
+    end
+    
+    system("./configure --prefix=#{File.expand_path("../")} --with-docs=no")
+    system("make")
+    system("make install")
+  elsif windows?
+    raise NotImplementedError, "need to specify build instructions for windows."
+  end
+end
+
+$INSTALLFILES = [
+  ["ruby_ndtypes.h", "$(archdir)"]
+]
+binaries = File.expand_path(File.join(File.dirname(__FILE__) + "/lib/"))
+headers = File.expand_path(File.join(File.dirname(__FILE__) + "/include/"))
+$LOAD_PATH << File.expand_path(binaries)
+
+["ndtypes"].each do |lib|
+  find_library(lib, nil, binaries)
+end
+
+["ndtypes.h"].each do |header|
+  find_header(header, headers)
+  have_header(header)
+end
+
+dir_config("ndtypes", [headers], [binaries])
+
+basenames = %w{gc_guard ruby_ndtypes}
+$objs = basenames.map { |b| "#{b}.o"   }
+$srcs = basenames.map { |b| "#{b}.c" }
+
+$CFLAGS += " -O0 -g "
+create_makefile("ruby_ndtypes/ruby_ndtypes")

data/ext/ruby_ndtypes/gc_guard.c

@@ -0,0 +1,36 @@
+/* Functions useful for interfacing shared rbuf objects with the Ruby GC. */
+/* Author: Sameer Deshmukh (@v0dro) */
+#include "ruby_ndtypes_internal.h"
+
+#define GC_GUARD_TABLE_NAME "@__gc_guard_table"
+
+static ID id_gc_guard_table;
+
+/* Unregister an NDT object-rbuf pair from the GC guard. */
+void
+rb_ndtypes_gc_guard_unregister(NdtObject *ndt)
+{
+  VALUE table = rb_ivar_get(mNDTypes_GCGuard, id_gc_guard_table);
+  rb_hash_delete(table, PTR2NUM(ndt));
+}
+
+/* Register a NDT-rbuf pair in the GC guard.  */
+void
+rb_ndtypes_gc_guard_register(NdtObject *ndt, VALUE rbuf)
+{
+  VALUE table = rb_ivar_get(mNDTypes_GCGuard, id_gc_guard_table);
+  if (table == Qnil) {
+    rb_raise(rb_eLoadError, "GC guard not initialized.");
+  }
+  
+  rb_hash_aset(table, PTR2NUM(ndt), rbuf);
+}
+
+/* Initialize the global GC guard table. klass is a VALUE reprensenting NDTypes class. */
+void
+rb_ndtypes_init_gc_guard(void)
+{
+  id_gc_guard_table = rb_intern(GC_GUARD_TABLE_NAME);
+  rb_ivar_set(mNDTypes_GCGuard, id_gc_guard_table, rb_hash_new());
+}
+

data/ext/ruby_ndtypes/gc_guard.h

@@ -0,0 +1,12 @@
+/* Header file containing various functions for GC guard table. */
+
+#ifndef GC_GUARD_H
+#define GC_GUARD_H
+
+#include "ruby_ndtypes_internal.h"
+
+void rb_ndtypes_gc_guard_unregister(NdtObject *ndt);
+void rb_ndtypesgc_guard_register(NdtObject *ndt, VALUE rbuf);
+void rb_ndtypes_init_gc_guard(VALUE cNDTypes);
+
+#endif  /* GC_GUARD_H */

data/ext/ruby_ndtypes/ndtypes/AUTHORS.txt

@@ -0,0 +1,5 @@
+
+Version 0.2.0
+-------------
+
+Stefan Krah <skrah@bytereef.org>, sponsored by Anaconda Inc. and Quansight LLC.

data/ext/ruby_ndtypes/ndtypes/INSTALL.txt

@@ -0,0 +1,101 @@
+
+
+Unix: libndtypes build instructions
+===================================
+
+# Build
+./configure
+make
+
+# Test
+make check
+
+# Install
+make install
+
+# Clean
+make clean
+
+# Distclean
+make distclean
+
+
+Windows: libndtypes build instructions
+======================================
+
+See vcbuild/INSTALL.txt.
+
+
+
+Unix/Windows: Python module build instructions
+==============================================
+
+To avoid shared library mismatches, the Python module builds with an rpath
+and ships the library inside the package.
+
+Unless you are a distributor with tight control over the system library
+versions, it is not recommended to install the library for the Python
+module.
+
+
+Build all
+---------
+
+# Build libndtypes and the module (libndtypes is copied into the package)
+python3 setup.py build
+
+# Test
+python3 setup.py test
+
+# Doctest (optional, relies on Sphinx)
+python3 setup.py doctest
+
+# Install
+python3 setup.py install
+
+# Clean libndtypes and the module
+python3 setup.py distclean
+
+
+Build the module only (for developing)
+--------------------------------------
+
+First, build libndtypes as above. This also copies the shared library into
+the package.  Then, to avoid rebuilding the library repeatedly, use:
+
+# Build the module
+python3 setup.py module
+
+# Clean the module
+python3 setup.py clean
+
+
+Alternative install (for developing)
+------------------------------------
+
+# Install the package into a local directory.  This is mainly useful for
+# developing xnd or gufuncs:
+python3 setup.py install --local="$PWD/../python"
+
+# Windows:
+python.exe setup.py install --local="%cd%\..\python"
+
+
+Alternative install with conda (for developing)
+-----------------------------------------------
+
+# Install the ndtypes package into a local directory.
+
+# Create and activate a new conda environment:
+conda create --name xnd python=3.7
+conda activate xnd
+
+# Use conda to build libndtypes and ndtypes:
+conda build .conda/libndtypes
+conda build .conda/ndtypes
+
+# Use conda to install the local version of the library and the
+# Python module:
+conda install --use-local ndtypes
+
+

data/ext/ruby_ndtypes/ndtypes/LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2017-2018, plures
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.