The Queue System

  • Overview

    The queue system is a system for module developers that lets them run code in the background so the user can get back to browsing faster. Things that take a long time to process should go into a queue.
  • What is the queueing system?

    The queueing system is a module feature of Jamroom that allows module developers to send tasks that take time into the background so the user who instigated that task does not have to wait for it to complete before continuing to browse the site.

    A good example of this is when an user uploads an audio file. The system wants to convert that audio file into multiple formats. The user who uploaded the file should not be forced to wait until conversion is finished before the upload completes processing.

    The audio conversion is sent to a queue to await processing while the uploader gets set on their way to do whatever they want to continue doing.
  • youtube
    Video screencast of how to use the queue system.
  • Q: Can someone explain how to create a module that uses worker queues that can run a command line tool on a conversion server?

    A: There's really nothing special about a module that uses queues - basically you:

    - register the name of the function that will be run when a queue entry is received that matches the queue - for example:

    jrCore_register_queue_worker('jrAudio', 'audio_conversions', 'jrAudio_convert_file', 0, 1);

    This tells the core:

    - when a new queue entry comes in to the "audio_conversions" queue
    - call the "jrAudio_convert_file" function and pass it $_queue - $_queue contains all the data that was passed in when the queue was created
    - "0" means there is NO LIMIT to the number of queue entries this function will process in a row (i.e. if you set it to "1" it would process 1 queue entry then exit).
    - the "1" says "only allow one function of this type to be running at the same time".

    From the worker function:

    - if you return TRUE the queue entry is deleted (that's how you tell the core you were succesful and the queue entry can now be removed).
    - if you return FALSE then the queue goes back into the stack for another worker to pickup
    - if you return a NUMBER it tells the core to "sleep" the queue for that many seconds - i.e. if you did:

    return 3600;

    it would put the queue entry back on the stack but not allow any worker to pick it up for 3600 seconds.

    So basically you just need to register the queue worker in the module's init function and that's it.
  • Fix stalled queues

    1) Pause Queues
    2) Run an integrity check with "repair modules" checked
    3) restart queues

    Then press RESET for that queue at the top.