pub struct Producer<S: Read + Write> { /* private fields */ }
Expand description
Producer
is used to enqueue new jobs that will in turn be processed by Faktory workers.
§Connecting to Faktory
To issue jobs, the Producer
must first be connected to the Faktory server. Exactly how you do
that depends on your setup. Faktory suggests using the FAKTORY_PROVIDER
and FAKTORY_URL
environment variables (see their docs for more information) with localhost:7419
as the
fallback default. If you want this behavior, pass None
to
Producer::connect
. If not, you can supply the URL
directly to Producer::connect
in the form:
protocol://[:password@]hostname[:port]
§Issuing jobs
Most of the lifetime of a Producer
will be spent creating and enqueueing jobs for Faktory
workers. This is done by passing a Job
to
Producer::enqueue
. The most important part of a Job
is its kind
; this field dictates how workers will execute the job when they receive it. The
string provided here must match a handler registered on the worker using
ConsumerBuilder::register
(or the equivalent
handler registration method in workers written in other languages).
Since Faktory workers do not all need to be the same (you could have some written in Rust for
performance-critical tasks, some in Ruby for more webby tasks, etc.), it may be the case that a
given job can only be executed by some workers (e.g., if they job type is not registered at
others). To allow for this, Faktory includes a labels
field with each job. Jobs will only be
sent to workers whose labels (see
ConsumerBuilder::labels
) match those set in
Job::labels
.
§Examples
Connecting to an unsecured Faktory server using environment variables
use faktory::Producer;
let p = Producer::connect(None).unwrap();
Connecting to a secured Faktory server using an explicit URL
use faktory::Producer;
let p = Producer::connect(Some("tcp://:hunter2@localhost:7439")).unwrap();
Issuing a job using a Producer
use faktory::Job;
p.enqueue(Job::new("foobar", vec!["z"])).unwrap();
Implementations§
source§impl Producer<TcpStream>
impl Producer<TcpStream>
sourcepub fn connect(url: Option<&str>) -> Result<Self, Error>
pub fn connect(url: Option<&str>) -> Result<Self, Error>
Connect to a Faktory server.
If url
is not given, will use the standard Faktory environment variables. Specifically,
FAKTORY_PROVIDER
is read to get the name of the environment variable to get the address
from (defaults to FAKTORY_URL
), and then that environment variable is read to get the
server address. If the latter environment variable is not defined, the connection will be
made to
tcp://localhost:7419
If url
is given, but does not specify a port, it defaults to 7419.
source§impl<S: Read + Write> Producer<S>
impl<S: Read + Write> Producer<S>
sourcepub fn connect_with(
stream: S,
pwd: Option<String>
) -> Result<Producer<S>, Error>
pub fn connect_with( stream: S, pwd: Option<String> ) -> Result<Producer<S>, Error>
Connect to a Faktory server with a non-standard stream.
sourcepub fn enqueue(&mut self, job: Job) -> Result<(), Error>
pub fn enqueue(&mut self, job: Job) -> Result<(), Error>
Enqueue the given job on the Faktory server.
Returns Ok
if the job was successfully queued by the Faktory server.
sourcepub fn enqueue_many<J>(
&mut self,
jobs: J
) -> Result<(usize, Option<HashMap<String, String>>), Error>
pub fn enqueue_many<J>( &mut self, jobs: J ) -> Result<(usize, Option<HashMap<String, String>>), Error>
Enqueue numerous jobs on the Faktory server.
Provided you have numerous jobs to submit, using this method will be more efficient as compared
to calling enqueue
multiple times.
The returned Ok
result will contain a tuple of enqueued jobs count and an option of a hash map
with job ids mapped onto error messages. Therefore Ok(n, None)
will indicate that all n jobs
have been enqueued without errors.
Note that this is not an all-or-nothing operation: jobs that contain errors will not be enqueued, while those that are error-free will be enqueued by the Faktory server.
sourcepub fn info(&mut self) -> Result<Value, Error>
pub fn info(&mut self) -> Result<Value, Error>
Retrieve information about the running server.
The returned value is the result of running the INFO
command on the server.
sourcepub fn queue_pause<T: AsRef<str>>(&mut self, queues: &[T]) -> Result<(), Error>
pub fn queue_pause<T: AsRef<str>>(&mut self, queues: &[T]) -> Result<(), Error>
Pause the given queues.
sourcepub fn queue_resume<T: AsRef<str>>(&mut self, queues: &[T]) -> Result<(), Error>
pub fn queue_resume<T: AsRef<str>>(&mut self, queues: &[T]) -> Result<(), Error>
Resume the given queues.
sourcepub fn start_batch(&mut self, batch: Batch) -> Result<BatchHandle<'_, S>, Error>
Available on crate feature ent
only.
pub fn start_batch(&mut self, batch: Batch) -> Result<BatchHandle<'_, S>, Error>
ent
only.Initiate a new batch of jobs.
sourcepub fn open_batch(
&mut self,
bid: String
) -> Result<Option<BatchHandle<'_, S>>, Error>
Available on crate feature ent
only.
pub fn open_batch( &mut self, bid: String ) -> Result<Option<BatchHandle<'_, S>>, Error>
ent
only.Open an already existing batch of jobs.
This will not error if a batch with the provided bid
does not exist,
rather Ok(None)
will be returned.