Skip to main content

​
Overview

The queue_controller provides administrative interfaces for managing the submission judging queue. It allows administrators to view queue status, manually trigger queue processing, unlock stuck items, and clear the entire queue.

​
Constructor

public function __construct()
Applies the following middleware:
  • auth - Requires user authentication

​
Methods

​
index()

public function index()
Displays the current state of the judging queue. Access Control:
  • Admin and head_instructor only
  • Aborts with 404 for other roles
Returns: View with:
  • All queue items (latest first)
  • Related submission data for each item
  • Processing status (locked/unlocked)
  • Queue type (judge/rejudge)
Route: /queue (GET) Example from controller: 
if (!in_array(Auth::user()->role->name, ['admin', 'head_instructor']))
    abort(404);
    
return view('admin.queue', [
    'queue' => Queue_item::with('submission')->latest()->get()
]);

​
work()

public function work()
Manually triggers queue processing for one item. Access Control:
  • Admin and head_instructor only
  • Aborts with 404 for other roles
Process:
  1. Calls Queue_item::work() static method
  2. Processes next available unlocked queue item
  3. Runs judging for associated submission
Returns: Redirect to queue index Route: /queue (POST) Example from controller: 
if (!in_array(Auth::user()->role->name, ['admin', 'head_instructor']))
    abort(404);
    
Queue_item::work();
return redirect(route('queue.index'));

​
unlock()

public function unlock($item)
Unlocks a stuck queue item by clearing its process ID.
​
item
integer
required
Queue item ID to unlock
Access Control:
  • Admin and head_instructor only
  • Aborts with 403 for other roles
Use Case: When a queue worker crashes or hangs, items may remain locked. This method clears the lock so the item can be processed again. Returns: Redirect to queue index Route: /queue/{item}/unlock (POST) Example from controller: 
if (!in_array(Auth::user()->role->name, ['admin', 'head_instructor'])) 
    abort(403);
    
$item = Queue_item::find($item);
$item->processid = NULL;
$item->save();

return redirect(route('queue.index'));

​
empty()

public function empty()
Clears the entire queue by deleting all queue items. Access Control:
  • Admin and head_instructor only
  • Aborts with 403 for other roles
Warning: This is a destructive operation. All pending submissions will be removed from the queue and will not be judged unless manually rejudged. Returns: Redirect to queue index Route: /queue/empty (POST) Example from controller: 
if (!in_array(Auth::user()->role->name, ['admin', 'head_instructor'])) 
    abort(403);
    
Queue_item::truncate();
return redirect(route('queue.index'));

​
Queue System Overview

​
Queue Item States

Unlocked (processid = NULL)
  • Item is available for processing
  • Worker can pick it up
Locked (processid set)
  • Item is being processed by a worker
  • processid contains the worker’s process ID
  • Other workers skip this item
Stuck
  • Item is locked but worker has crashed/died
  • processid points to non-existent process
  • Requires manual unlock

​
Queue Processing Flow

  1. Submission Created
    • User submits code
    • Queue item created with type ‘judge’
    • Automatic processing triggered
  2. Worker Picks Item
    • Worker calls Queue_item::work()
    • Finds first unlocked item
    • Locks item with process ID
  3. Judging Execution
    • Worker runs test cases
    • Updates submission status
    • Writes results to files
  4. Completion
    • Queue item deleted
    • Submission marked complete
    • Scoreboard updated if final submission

​
Queue Types

judge
  • New submission from user
  • First time judging this submission
  • Created by submission_controller::store()
rejudge
  • Re-evaluation of existing submission
  • Created by submission_controller::rejudge()
  • Used when test cases or time limits change

​
Queue Management Scenarios

​
Scenario 1: Queue Not Processing

Symptoms:
  • Submissions stuck in PENDING status
  • Queue items accumulating
  • No recent completion activity
Diagnosis:
  1. Check queue page
  2. Look for locked items with old timestamps
  3. Check if worker processes exist
Solution:
  1. Kill hung worker processes (if any)
  2. Unlock stuck items via UI
  3. Click “Work” to manually trigger processing
  4. Check queue settings (concurrent workers)

​
Scenario 2: Queue Overflow

Symptoms:
  • Hundreds/thousands of queue items
  • System slow or unresponsive
  • Students reporting long wait times
Diagnosis:
  1. Check queue page for item count
  2. Review recent activity (exam? deadline?)
  3. Check server resources (CPU, memory)
Solution:
  1. Increase concurrent workers in settings
  2. Consider clearing old queue items
  3. Restart queue workers
  4. Add more worker servers if needed

​
Scenario 3: Corrupt Queue

Symptoms:
  • Workers crashing repeatedly
  • Error messages in logs
  • Items processing but failing
Diagnosis:
  1. Review error logs
  2. Check specific submission causing issues
  3. Verify test case files exist
Solution:
  1. Empty entire queue using “Empty” button
  2. Fix underlying issue (test cases, permissions, etc.)
  3. Rejudge affected submissions

​
Administrative Best Practices

​
Regular Monitoring

  • Check queue page daily during active periods
  • Set up alerts for queue depth > threshold
  • Monitor worker process health
  • Review completion rates

​
Maintenance Windows

  • Schedule during low-activity periods
  • Announce to users in advance
  • Empty queue before major updates
  • Test with small queue after changes

​
Disaster Recovery

  • Document queue clearing procedures
  • Keep list of recent submission IDs
  • Have rejudge scripts ready
  • Maintain backup of test cases

​
Queue_item Model

Fields:
  • id - Primary key
  • submission_id - Foreign key to submissions
  • processid - Lock indicator (NULL = unlocked)
  • type - Queue type (judge/rejudge)
  • created_at - Timestamp
  • updated_at - Timestamp
Key Methods:
  • work() - Process next item
  • add_and_process() - Add item and trigger processing
  • add_not_process() - Add item without triggering

​
Submission Model

Queue items reference submissions:
  • Each queue item processes one submission
  • Submission status updated during processing
  • Results written to submission’s directory

​
Settings

concurent_queue_process
  • Number of simultaneous queue workers
  • Default: 2
  • Increase for high-load periods
  • Adjust based on server capacity

​
Routes Summary

MethodRouteActionDescription
GET/queueindex()View queue status
POST/queuework()Process next item
POST/queue/{item}/unlockunlock()Unlock stuck item
POST/queue/emptyempty()Clear entire queue
  • Queue_item: Queue item records
  • Submission: Submissions being judged
  • Assignment: Assignment context
  • Problem: Problem being judged
  • Setting: Queue configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us