Skip to content

Latest commit

 

History

History
109 lines (88 loc) · 5.17 KB

Ref_WorkServerAdapter_interface.md

File metadata and controls

109 lines (88 loc) · 5.17 KB
Raw

WorkServerAdapter Interface

Declaration: interface mle86\WQ\WorkServerAdapter\WorkServerAdapter
Source file: src/WQ/WorkServerAdapter/WorkServerAdapter.php

A Work Server stores jobs inside one or more Work Queues.

A WorkServerAdapter implementation uses a connection handle to an existing Work Server: for example, the RedisWorkServer implementation (from the mle86/wq-redis package) takes a \Redis instance from the phpredis extension.

A Beanstalkd server or a Redis server might be such a Work Server. In case of Beanstalkd, Work Queues are Tubes; in case of Redis, Work Queues are Lists.

Methods

  • public function getNextQueueEntry ($workQueue, int $timeout = DEFAULT_TIMEOUT): ?QueueEntry
    This takes the next job from the named work queue(s) and returns it.
    This method will reserve the returned job for a short time. If you want to delete/bury/re-queue the job, use the deleteEntry/buryEntry/requeueEntry methods. Keep in mind to check the Job::jobIsExpired() flag before executing the job.
    If you don't want to do all of this manually, use WorkProcessor::processNextJob() instead.
    Returns null if no job was available after waiting for $timeout seconds.
    • $workQueue: The name of the Work Queue to poll (string) or an array of Work Queues to poll. In the latter case, the first job in any of these Work Queues will be returned.
    • $timeout: How many seconds to wait for a job to arrive, if none is available immediately. Set this to NOBLOCK if the method should return immediately. Set this to FOREVER if the call should block until a job becomes available, no matter how long it takes.

  • public function storeJob (string $workQueue, Job $job, int $delay = 0): void
    Stores a job in the work queue for later processing.
    • $workQueue: The name of the Work Queue to store the job in.
    • $job: The job to store.
    • $delay: The job delay in seconds after which it will become available to getNextQueueEntry(). Set to zero (default) for jobs which should be processed as soon as possible.

  • public function buryEntry (QueueEntry $entry): void
    Buries an existing job so that it won't be returned by getNextQueueEntry() again but is still present in the system for manual inspection.
    This is what happens to failed jobs.

  • public function requeueEntry (QueueEntry $entry, int $delay, string $workQueue = null): void
    Re-queues an existing job so that it can be returned by getNextQueueEntry() again at some later time. A $delay is required to prevent the job from being returned right after it was re-queued.
    This is what happens to failed jobs which can still be re-queued for a retry.
    • $entry: The job to re-queue. The instance should not be used anymore after this call.
    • $delay: The job delay in seconds. It will become available to getNextQueueEntry() after this delay.
    • $workQueue: By default, to job is re-queued into its original Work Queue. With this parameter, a different Work Queue can be chosen.

  • public function deleteEntry (QueueEntry $entry): void
    Permanently deletes a job entry for its work queue.
    This is what happens to finished jobs.

  • public function disconnect (): void
    Explicitly closes the connection to the work server.
    The instance should not be used anymore after calling this method; calling other methods afterwards is likely to lead to unexpected behaviour such as connection-related exceptions. Repeated calls to this method have no effect. The class destructor should also call this, so there's rarely a good reason for calling this method outside of testing.

Constants

  • const int DEFAULT_TIMEOUT = 5
    The default timeout for getNextQueueEntry(), in seconds.
  • const NOBLOCK
    Causes getNextQueueEntry() to return immediately.
  • const FOREVER
    Causes getNextQueueEntry() to block indefinitely, until a job becomes available.

Implementations

This package also includes a few implementations of the WorkServerAdapter interface:

  • the AffixAdapter which serves as a queue name changer for other WorkServerAdapter implementations,
  • the BlackHoleWorkServer which doesn't actually store anything,
  • and the MemoryWorkServer which uses a class member array for persistence.

Other, more interesting implementations are provided in different packages – see “Adapter Implementations” in the readme document.