Dispatching Jobs

Dispatching jobs is the primary way to execute work in the Hypervel Bus system. This page provides an overview of job dispatching mechanisms, covering synchronous execution, asynchronous queuing, and job configuration. For batch processing of multiple jobs, see page 7.

Overview

The Hypervel Bus provides two main entry points for dispatching jobs:

Function	Purpose	Return Type	Execution
dispatch()	Asynchronous job dispatch with configuration	PendingDispatch or PendingClosureDispatch	Queued for later processing
dispatch_sync()	Synchronous job dispatch	Mixed (job result)	Immediate execution in current process

Both functions are defined in src/Functions.php and serve as the primary user-facing API for the bus system.

Job Dispatching Architecture

Sources: src/Functions.php1-36 src/PendingDispatch.php15-174

Asynchronous Dispatch with dispatch()

The dispatch() function is the primary entry point for asynchronous job processing. It returns a PendingDispatch instance that enables fluent configuration before the job is dispatched.

Basic Mechanism

Asynchronous Dispatch Lifecycle

The dispatch process has two key phases:

1. Configuration Phase: The PendingDispatch instance is returned, allowing method chaining to configure the job (queue name, delay, connection, etc.)
2. Auto-Dispatch Phase: When the PendingDispatch object is destroyed (goes out of scope), its __destruct() method automatically dispatches the job to the queue

This deferred dispatch pattern ensures jobs are always dispatched while enabling fluent configuration.

Sources: src/Functions.php12-23 src/PendingDispatch.php15-174

Closure Jobs

When dispatch() receives a closure instead of a job object, it wraps the closure in a CallQueuedClosure object (from hypervel/queue) to make it serializable for queue storage:

Closure Dispatch Flow

Sources: src/Functions.php18-23

For detailed information on configuring dispatched jobs, see page 4.2.

Synchronous Dispatch with dispatch_sync()

The dispatch_sync() function executes jobs immediately in the current process and returns the result. It bypasses the queue system entirely.

Synchronous Dispatch Flow

The dispatch_sync() function:

1. Resolves the Dispatcher from the DI container using ApplicationContext::getContainer()
2. Calls dispatchSync($job, $handler) on the dispatcher
3. The dispatcher locates the appropriate handler (or uses the provided one)
4. Executes the handler immediately and returns the result

This is useful when you need the job's return value or must complete the work before proceeding.

Sources: src/Functions.php25-35

Configuration and Queue Integration

The PendingDispatch class provides a fluent interface for configuring jobs before they are dispatched. Configuration methods include:

Method	Purpose	File Reference
onQueue()	Set the queue name	src/PendingDispatch.php43-48
onConnection()	Set the queue connection	src/PendingDispatch.php33-38
delay()	Delay job execution	src/PendingDispatch.php73-78
afterCommit()	Wait for database commits	src/PendingDispatch.php93-98
chain()	Add jobs to execute after success	src/PendingDispatch.php113-118
afterResponse()	Dispatch after HTTP response	src/PendingDispatch.php123-128

All configuration methods return $this, enabling method chaining:

For comprehensive coverage of configuration options, see page 4.2. For details on queue integration and the ShouldQueue interface, see page 4.3.

Sources: src/PendingDispatch.php30-154

Dispatch Triggers and Timing

Jobs configured with PendingDispatch are dispatched at specific trigger points:

PendingDispatch Lifecycle and Triggers

The automatic dispatch on object destruction ensures that jobs are always dispatched, even if the developer forgets to explicitly call a dispatch method. The shouldDispatch() method checks for unique job constraints before dispatching (see page 8.1 for unique jobs).

Sources: src/PendingDispatch.php131-173

The Dispatcher Interface

The Dispatcher interface (src/Contracts/Dispatcher.php8-45) defines the core contract for job dispatching:

Method	Purpose	Usage Context
dispatch($command)	Dispatch job (async if queueable)	Called by PendingDispatch::__destruct()
dispatchSync($command, $handler)	Dispatch job synchronously	Called by dispatch_sync() function
dispatchNow($command, $handler)	Execute job immediately	Internal use
hasCommandHandler($command)	Check if handler exists	Handler resolution
getCommandHandler($command)	Retrieve job handler	Handler resolution
pipeThrough($pipes)	Set middleware pipeline	Configuration
map($map)	Map commands to handlers	Configuration

The concrete implementation of this interface is provided by the dispatcher service registered in src/ConfigProvider.php

Sources: src/Contracts/Dispatcher.php8-45

Related Topics

This page provides an overview of job dispatching. For more specific topics:

• Page 4.1: Detailed documentation of dispatch() and dispatch_sync() functions
• Page 4.2: Complete guide to PendingDispatch configuration options
• Page 4.3: Queue integration, ShouldQueue interface, and async execution
• Page 5: Job traits (Dispatchable, Queueable, Batchable) that simplify job creation
• Page 6: Job chaining for sequential execution
• Page 7: Batch processing for groups of jobs

Dispatching Jobs Asynchronously

Asynchronous job dispatching is handled by the dispatch() function, which prepares a job for execution on a queue.

The dispatch() Function

The dispatch() function is the main entry point for asynchronous job processing:

Dispatch Function Flow

Sources: src/Functions.php18-23

The dispatch() function handles two types of jobs:

1. Regular job objects: These are placed directly into a PendingDispatch instance
2. Closure functions: These are wrapped in CallQueuedClosure and placed into a PendingClosureDispatch instance

Usage Examples

To dispatch a job asynchronously:

The dispatch() function returns either a PendingDispatch or PendingClosureDispatch object, which allows for method chaining to configure the dispatch operation.

Sources: src/Functions.php12-23

Dispatching Jobs Synchronously

For immediate job execution in the current process, use the dispatch_sync() function.

The dispatch_sync() Function

The dispatch_sync() function is used when you need to execute a job immediately and wait for its result:

Synchronous Dispatch Sequence

Sources: src/Functions.php30-35 src/Contracts/Dispatcher.php14-19

The dispatch_sync() function:

1. Retrieves the Dispatcher instance from the dependency injection container
2. Calls the dispatchSync() method on the dispatcher
3. The dispatcher finds and executes the appropriate handler for the job
4. The result is returned immediately to the caller

Usage Example

Sources: src/Functions.php25-35

The Dispatcher Interface

At the core of the job dispatching system is the Dispatcher interface, which defines the contract for dispatching jobs.

Dispatcher Interface Hierarchy

Sources: src/Contracts/Dispatcher.php8-45

The Dispatcher interface provides methods for:

• Dispatching commands/jobs (both sync and async)
• Checking for and retrieving command handlers
• Configuring command pipelines
• Mapping commands to handlers

Handler Resolution

When a job is dispatched, the dispatcher determines which handler should process it. Handlers can be:

1. Explicitly defined: When using the map() method on the dispatcher
2. Automatically resolved: Based on naming conventions or metadata

The dispatcher uses these methods to find the appropriate handler:

• Checking any explicitly mapped handlers
• Looking for a handle method on the job itself
• Resolving a handler class based on the job's class name

Sources: src/Contracts/Dispatcher.php27-34

Integration with Queue System

For asynchronous processing, the Bus system integrates with the queue system. When a job is dispatched asynchronously:

1. The job is prepared for queuing (serialized if necessary)
2. For closures, they are wrapped in CallQueuedClosure to make them serializable
3. The job is pushed to the appropriate queue
4. A queue worker will later retrieve and execute the job

For more details on queue integration, see Queue Integration.

Sources: src/Functions.php18-23

Command Pipeline

The Bus system supports middleware-like processing through command pipelines. Using the pipeThrough() method on the dispatcher, you can specify a series of pipes that each command should pass through before reaching its handler.

This feature is useful for implementing cross-cutting concerns such as:

• Logging
• Authorization
• Validation
• Transaction management

Sources: src/Contracts/Dispatcher.php38-39

Summary

The Hypervel Bus dispatching system provides a flexible and powerful way to handle jobs in your application:

Dispatching Method	Function	Use Case
Asynchronous	dispatch()	Background processing, non-blocking operations
Synchronous	dispatch_sync()	Immediate execution, when result is needed right away

By understanding these dispatching mechanisms, you can effectively implement job processing in your application, choosing the appropriate approach based on your specific requirements.