hallon 0.11.0 → 0.12.0

data/hallon.gemspec

@@ -21,8 +21,8 @@ Gem::Specification.new do |gem|
   gem.platform    = Gem::Platform::RUBY
   gem.required_ruby_version = '~> 1.8'
 
-  gem.add_dependency 'spotify', '~> 10.1.1'
-  gem.add_development_dependency 'bundler', '~> 1.0'
+  gem.add_dependency 'ref', '~> 1.0'
+  gem.add_dependency 'spotify', '~> 10.3.0'
   gem.add_development_dependency 'rake', '~> 0.8'
   gem.add_development_dependency 'rspec', '~> 2'
   gem.add_development_dependency 'yard'

data/lib/hallon.rb

@@ -9,8 +9,20 @@ require 'hallon/linkable'
 require 'hallon/version'
 require 'hallon/error'
 require 'hallon/base'
+require 'hallon/queue'
 require 'hallon/enumerator'
 
+require 'hallon/observable/album_browse'
+require 'hallon/observable/artist_browse'
+require 'hallon/observable/image'
+require 'hallon/observable/playlist_container'
+require 'hallon/observable/playlist'
+require 'hallon/observable/post'
+require 'hallon/observable/session'
+require 'hallon/observable/search'
+require 'hallon/observable/toplist'
+require 'hallon/observable/player'
+
 require 'hallon/session'
 require 'hallon/link'
 require 'hallon/user'
@@ -26,6 +38,9 @@ require 'hallon/artist_browse'
 require 'hallon/player'
 require 'hallon/search'
 
+# Why is this not the default in Ruby?
+Thread.abort_on_exception = true
+
 # The Hallon module wraps around all Hallon objects to avoid polluting
 # the global namespace. To start using Hallon, you most likely want to
 # be looking for the documentation on {Hallon::Session}.

data/lib/hallon/album.rb

@@ -84,7 +84,7 @@ module Hallon
     def cover(as_image = true)
       if as_image
         cover = Spotify.album_cover(pointer)
-        Image.new cover.read_string(20) unless cover.null?
+        Image.from(cover)
       else
         cover = Spotify.link_create_from_album_cover!(pointer)
         Link.from(cover)

data/lib/hallon/album_browse.rb

@@ -7,7 +7,7 @@ module Hallon
   # @see Album
   # @see http://developer.spotify.com/en/libspotify/docs/group__albumbrowse.html
   class AlbumBrowse < Base
-    include Observable
+    extend Observable::AlbumBrowse
 
     # Creates an AlbumBrowse instance from an Album or an Album pointer.
     #
@@ -22,8 +22,9 @@ module Hallon
         raise TypeError, "expected album pointer, was given #{given}"
       end
 
-      @callback = proc { trigger(:load) }
-      @pointer  = Spotify.albumbrowse_create!(session.pointer, pointer, @callback, nil)
+      subscribe_for_callbacks do |callback|
+        @pointer = Spotify.albumbrowse_create!(session.pointer, pointer, callback, nil)
+      end
 
       raise FFI::NullPointerError, "album browsing failed" if @pointer.null?
     end

data/lib/hallon/artist.rb

@@ -49,7 +49,7 @@ module Hallon
     def portrait(as_image = true)
       if as_image
         portrait = Spotify.artist_portrait(pointer)
-        Image.new portrait.read_bytes(20) unless portrait.null?
+        Image.from(portrait)
       else
         portrait = Spotify.link_create_from_artist_portrait!(pointer)
         Link.from(portrait)

data/lib/hallon/artist_browse.rb

@@ -5,7 +5,7 @@ module Hallon
   # @see Artist
   # @see http://developer.spotify.com/en/libspotify/docs/group__artistbrowse.html
   class ArtistBrowse < Base
-    include Observable
+    extend Observable::ArtistBrowse
 
     # @return [Array<Symbol>] artist browsing types for use in {#initialize}
     def self.types
@@ -26,8 +26,9 @@ module Hallon
         raise TypeError, "expected artist pointer, was given #{given}"
       end
 
-      @callback = proc { trigger(:load) }
-      @pointer  = Spotify.artistbrowse_create!(session.pointer, pointer, type, @callback, nil)
+      subscribe_for_callbacks do |callback|
+        @pointer = Spotify.artistbrowse_create!(session.pointer, pointer, type, callback, nil)
+      end
 
       raise FFI::NullPointerError, "artist browsing failed" if @pointer.null?
     end
@@ -70,7 +71,7 @@ module Hallon
       size = Spotify.artistbrowse_num_portraits(pointer)
       Enumerator.new(size) do |i|
         if as_image
-          id = Spotify.artistbrowse_portrait(pointer, i).read_string(20)
+          id = Spotify.artistbrowse_portrait(pointer, i)
           Image.new(id)
         else
           link = Spotify.link_create_from_artistbrowse_portrait!(pointer, i)

data/lib/hallon/base.rb

@@ -3,10 +3,15 @@ module Hallon
   # All objects in Hallon are mere representations of Spotify objects.
   # Hallon::Base covers basic functionality shared by all of these.
   class Base
-    # @param [#null?] pointer
+    # @param [#nil?, #null?] pointer
     # @return [self, nil] a new instance of self, unless given pointer is #null?
     def self.from(pointer, *args, &block)
-      new(pointer, *args, &block) unless pointer.null?
+      is_nil  = pointer.nil?
+      is_null = pointer.null? if pointer.respond_to?(:null?)
+
+      unless is_nil or is_null
+        new(pointer, *args, &block)
+      end
     end
 
     # Underlying FFI pointer.

data/lib/hallon/error.rb

@@ -49,7 +49,7 @@ module Hallon
       # @param [Fixnum, Symbol] error
       # @return [nil]
       def maybe_raise(x)
-        return nil if [nil, :timeout].include?(x)
+        return nil if [nil, :timeout, :is_loading].include?(x)
 
         error, symbol = disambiguate(x)
         return symbol if symbol == :ok

data/lib/hallon/ext/spotify.rb

@@ -122,7 +122,7 @@ module Spotify
 
     # @return [String] representation of the spotify pointer
     def to_s
-      "<#{self.class} address=#{address} type=#{type}>"
+      "<#{self.class} address=0x#{address.to_s(16)} type=#{type}>"
     end
 
     # Create a proc that will accept a pointer of a given type and
@@ -142,14 +142,8 @@ module Spotify
     # @param [Object] pointer
     # @param [Symbol] type (optional, no type checking is done if not given)
     # @return [Boolean] true if object is a spotify pointer and of correct type
-    def self.typechecks?(object, type = nil)
-      if ! object.is_a?(Spotify::Pointer)
-        false
-      elsif type
-        object.type == type.to_s
-      else
-        true
-      end
+    def self.typechecks?(object, type)
+      !! (object.type == type.to_s) if object.is_a?(Spotify::Pointer)
     end
   end
 
@@ -200,51 +194,41 @@ module Spotify
   end
 
   # Makes it easier binding callbacks safely to callback structs.
-  # When including this class you *must* define `proc_for(member)`!
+  #
+  # @see add
+  # @see remove
   module CallbackStruct
-    # Assigns the callbacks to call the given target; the callback
-    # procs are stored in the `storage` parameter. **Make sure the
-    # storage does not get garbage collected as long as these callbacks
-    # are needed!**
+    # Before assigning [member]=(callback), inspect the arity of
+    # said callback and raise an ArgumentError if they don‘t match.
     #
-    # @param [Object] target
-    # @param [#&#91;&#93;&#61;] storage
-    def create(target, storage)
-      new.tap do |struct|
-        members.each do |member|
-          struct[member] = storage[member] = proc_for(target, member)
-        end
+    # @raise ArgumentError if the arity of the given callback does not match the member
+    def []=(member, callback)
+      unless callback.arity < 0 or callback.arity == arity_of(member)
+        raise ArgumentError, "#{member} callback takes #{arity_of(member)} arguments, was #{callback.arity}"
+      else
+        super
       end
     end
-  end
 
-  class << SessionCallbacks
-    include CallbackStruct
+    protected
 
-    private
-      # @see CallbackStruct
-      def proc_for(target, member)
-        lambda { |pointer, *args| target.trigger(member, *args) }
-      end
+    # @param [Symbol] member
+    # @return [Integer] arity of the given callback member
+    def arity_of(member)
+      fn = layout[member].type
+      fn.param_types.size
+    end
   end
 
-  class << PlaylistCallbacks
+  SessionCallbacks.instance_eval do
     include CallbackStruct
-
-    private
-      # @see CallbackStruct
-      def proc_for(target, member)
-        lambda { |pointer, *args, userdata| target.trigger(member, *args) }
-      end
   end
 
-  class << PlaylistContainerCallbacks
+  PlaylistCallbacks.instance_eval do
     include CallbackStruct
+  end
 
-    private
-      # @see CallbackStruct
-      def proc_for(target, member)
-        lambda { |pointer, *args, userdata| target.trigger(member, *args) }
-      end
+  PlaylistContainerCallbacks.instance_eval do
+    include CallbackStruct
   end
 end

data/lib/hallon/image.rb

@@ -12,8 +12,7 @@ module Hallon
 
     to_link :from_image
 
-    # Image triggers `:load` when loaded
-    include Observable
+    extend Observable::Image
 
     # Create a new instance of an Image.
     #
@@ -30,13 +29,13 @@ module Hallon
       end
 
       @pointer = to_pointer(link, :image) do
-        ptr = FFI::MemoryPointer.new(:char, 20)
-        ptr.write_bytes(link)
-        Spotify.image_create!(session.pointer, ptr)
+        Spotify.image_create!(session.pointer, link)
       end
 
-      @callback = proc { trigger :load }
-      Spotify.image_add_load_callback(pointer, @callback, nil)
+      subscribe_for_callbacks do |callbacks|
+        Spotify.image_remove_load_callback(pointer, callbacks, nil)
+        Spotify.image_add_load_callback(pointer, callbacks, nil)
+      end
     end
 
     # @return [Boolean] true if the image is loaded.
@@ -58,7 +57,7 @@ module Hallon
     # @param [Boolean] raw true if you want the image id as a hexadecimal string
     # @return [String] image ID as a string.
     def id(raw = false)
-      id = Spotify.image_image_id(pointer).read_string(20)
+      id = Spotify.image_image_id(pointer)
       raw ? id : to_hex(id)
     end
 

data/lib/hallon/observable.rb

@@ -1,87 +1,159 @@
 # coding: utf-8
+require 'ref'
+
 module Hallon
   # A module providing event capabilities to Hallon objects.
   #
   # @private
   module Observable
+    # This module is responsible for creating methods for registering
+    # callbacks. It expects a certain protocol to already available.
+    module ClassMethods
+      # When extended it’ll call #initialize_observable to set-up `other`.
+      def self.extended(other)
+        other.send(:initialize_observable)
+      end
+
+      # @return [Method, Struct] callbacks to attach to this object
+      attr_reader :callbacks
+
+      # Subscribe to callbacks for a given pointer.
+      #
+      # @param [Object] object
+      # @param [FFI::Pointer] pointer
+      def subscribe(object, pointer)
+        key = pointer.address
+        ref = Ref::WeakReference.new(object)
+
+        @lock.synchronize do
+          if @subscribers_rev[ref.referenced_object_id]
+            raise ArgumentError, "already subscribed to callbacks"
+          end
+
+          @subscribers[key] ||= {} # use a hash for fast reverse lookups
+          @subscribers[key][ref.referenced_object_id] = ref
+          @subscribers_rev[ref.referenced_object_id] = key
+        end
+
+        ObjectSpace.define_finalizer(object, @unsubscriber)
+      end
+
+      # Retrieve all subscribers for a given pointer.
+      #
+      # @param [FFI::Pointer] pointer
+      def subscribers_for(pointer)
+        key = pointer.address
+
+        @lock.synchronize do
+          @subscribers.fetch(key, {}).values.map(&:object).compact
+        end
+      end
+
+      protected
+
+      # Run when ClassMethods are extended.
+      #
+      # It sets up the callbacks and all book-keeping required to keep
+      # track of all subscribers properly.
+      def initialize_observable
+        @callbacks = initialize_callbacks
+
+        @lock = Ref::SafeMonitor.new
+        @subscribers = {}
+        @subscribers_rev = {}
+        @unsubscriber = proc do |object_id|
+          @lock.synchronize do
+            if key = @subscribers_rev.delete(object_id)
+              @subscribers[key].delete(object_id)
+              @subscribers.delete(key) if @subscribers[key].empty?
+            end
+          end
+        end
+      end
+
+      # @param [#to_s] name
+      # @return [Method]
+      def callback_for(name)
+        method("#{name}_callback")
+      end
+
+      # Scans through the list of subscribers, trying to find any
+      # subscriber attached to this pointer. For each subscriber,
+      # trigger the appropriate event.
+      #
+      # @param [FFI::Pointer] pointer
+      # @param [Symbol] event
+      # @param […] arguments
+      # @return whatever the (last) handler returned
+      def trigger(pointer, event, *arguments)
+        subscribers_for(pointer).inject(nil) do |_, subscriber|
+          # trigger is protected, inconvenient but symbolic
+          subscriber.send(:trigger, event, *arguments)
+        end
+      end
+    end
+
+    # Will extend `other` with {ClassMethods}.
+    def self.included(other)
+      other.extend(ClassMethods)
+    end
+
     # Defines a handler for the given event.
     #
-    # @example defining a handler and triggering it
-    #   on(:callback) do |message|
-    #     puts message
-    #   end
-    #
-    #   trigger(:callback, "Moo!") # => prints "Moo!"
-    #
-    # @example multiple events with one handler
-    #   on(:a, :b, :c) do |name, *args|
-    #     puts "#{name} called with: #{args.inspect}"
-    #   end
-    #
-    #   trigger(:a) # => prints ":a called with: []"
-    #   trigger(:b, :c) # => prints ":b called with: [:c]"
-    #
-    # @note when defining a handler for multiple events, the
-    #       first argument passed to the handler is the name
-    #       of the event that called it
-    # @param [#to_sym] event name of event to handle
+    # @param [#to_s] event name of event to handle
+    # @return [Proc] the given block
     # @yield (*args) event handler block
-    def on(*events, &block)
+    def on(event, &block)
       raise ArgumentError, "no block given" unless block
-      wrap = events.length > 1
-      events.map(&:to_sym).each do |event|
-        block = proc { |*args| yield(event, *args) } if wrap
-        __handlers[event] = [] unless __handlers.has_key?(event)
-        __handlers[event] << block
-      end
+      raise NameError, "no such callback: #{event}" unless has_callback?(event)
+      handlers[event.to_s] = block
     end
 
-    # Trigger a handler for a given event.
-    #
-    # @param [#to_sym] event
-    # @param [Object, ...] params given to each handler
-    def trigger(event, *params, &block)
-      catch :return do
-        return_value = nil
-        __handlers[event.to_sym].each do |handler|
-          return_value = handler.call(*params, &block)
-        end
-        return_value
-      end
+    # @param [#to_s] name
+    # @return [Boolean] true if a callback with `name` exists.
+    def has_callback?(name)
+      self.class.respond_to?("#{name}_callback", true)
     end
 
-    # Run the given block, protecting all previous event handlers.
-    #
-    # @example
-    #   o = Object.new
-    #   o.instance_eval { include Hallon::Base }
-    #   o.on(:method) { "outside" }
+    # Run a given block, and once it exits restore all handlers
+    # to the way they were before running the block.
     #
-    #   puts o.on_method # => "outside"
-    #   o.protecting_handlers do
-    #     o.on(:method) { "inside" }
-    #     puts o.on_method # => "inside"
-    #   end
-    #   puts o.on_method # => "outside"
+    # This allows you to temporarily use different handlers for
+    # some events.
     #
     # @yield
-    # @return whatever the given block returns
     def protecting_handlers
-      deep_copy = __handlers.dup.clear
-      __handlers.each do |k, v|
-        deep_copy[k] = v.dup
-      end
+      old_handlers = handlers.dup
       yield
     ensure
-      __handlers.replace deep_copy
+      handlers.replace(old_handlers)
     end
 
-    private
-      # Hash mapping events to handlers.
-      #
-      # @return [Hash]
-      def __handlers
-        @__handlers ||= Hash.new([])
+    protected
+
+    # Register this object as interested in callbacks.
+    #
+    # @yield [callback]
+    # @yieldparam [Method, Struct] callback (always the same object)
+    # @return whatever the block returns
+    def subscribe_for_callbacks
+      yield(self.class.callbacks).tap do
+        self.class.subscribe(self, pointer)
       end
+    end
+
+    # @param [#to_s] name
+    # @param [...] arguments
+    # @return whatever the handler returns
+    def trigger(name, *arguments, &block)
+      if handler = handlers[name.to_s]
+        handler.call(*arguments, self, &block)
+      end
+    end
+
+    # @return [Hash<String, Proc>]
+    def handlers
+      @__handlers ||= Hash.new(proc {})
+    end
   end
 end