Hooks api

Showing 1-4 of 4 messages
Hooks api Brandon Keepers 10/10/11 8:37 PM
Hello Qu Comrades (all 3 of you),

I've started working on an implementation of hooks and thought I would get some feedback before going any further.


To summarize the major changes: Jobs must now extend Qu::Job. This is something I debated about a lot in the initial implementation of Qu. I initially implemented it as a subclass of Qu::Job, but then decided follow Resque and make jobs simply a class with a perform class method for simplicity's sake. I have since changed my mind and think there's a lot of power in using richer objects for jobs.

The Qu:Job class currently implements 4 hooks (perform, complete, release, failure). Others will be coming soon, but I still need to figure out some implementation details.  A hook is a method that is called before, after, or around one of the events.  Calling `halt` in a before hook will prevent the original action from occurring (example: `halt` in a before_failure hook will prevent the job from being marked as failed) and will stop all other hooks.

Here are some examples of what a job using hooks will look like:

class MyJob < Qu::Job
  attr_reader :thing

  around_perform :timeout  
  before_perform :notify_before_perform
  after_perform :notify_before_perform

  before_failure :ignore_annoying_errors

  def initialize(thing_id)
    @thing = Thing.find(thing_id)
  end

  def perform
    # …
  end

private

  def notify_before_perform
    notifier.announce "Performing job #{id}"
  end

  def notify_after_perform
    notifier.announce "Done performing job #{id}"
  end

  def ignore_annoying_errors(e)
    halt if e < ErrorIDoNotCareAbout
  end

  def timeout
    Timeout.timeout(60) do
      yield
    end
  end
end


So, what do you think so far? Anything you would do differently?

Thanks,
Brandon
Re: [Qu] Hooks api Jonathan Hoyt 10/11/11 7:10 AM
Looks good to me. How do you handle completely changing the API on a library and letting folks know that you did so? Just update the readme, or do you try and reach out to those you know are using it?
Re: [Qu] Hooks api Brandon Keepers 10/11/11 7:27 AM
Once Qu reaches 1.0, I'll follow semantic versioning (http://semver.org/). Until then, I'll document it and make it clear that any change in minor version (0.1 => 0.2) will be backwards incompatible.

Since qu is so new and has so few users, I'm not too worried about it.

=b
Re: [Qu] Hooks api Craig Wickesser 10/12/11 2:24 AM
I'm cool with having to subclass Qu::Job. I generally don't like having to subclass something but in the case of a "job" class, they already tend to be lean and focused (in my experience so far).

One thing I'd like is clear documentation (maybe even a flow diagram, or something similar) about the hooks, when are they invoked? what happens if an exception is raised inside of a hook? what happens when you call "halt" (i.e. in a before_perform hook?).

-craig