Worker_jobs

class dvg_qdeviceio.Worker_jobs(qdev, jobs_function=None, debug=False, **kwargs)

Bases: QObject

This worker maintains a thread-safe queue where desired device I/O operations, called jobs, can be put onto. The worker will send out the operations to the device, first-in, first-out (FIFO), until the queue is empty again. The manner in which each job gets handled is explained by initialization parameter jobs_function.

An instance of this worker will be created and placed inside a new thread by a call to QDeviceIO.create_worker_jobs().

This worker uses the QWaitCondition mechanism. Hence, it will only send out all pending jobs on the queue, whenever the thread is woken up by a call to Worker_jobs.process_queue(). When it has emptied the queue, the thread will go back to sleep again.

Parameters:

• qdev (QDeviceIO) – Reference to the parent QDeviceIO class instance, automatically set when being initialized by QDeviceIO.create_worker_jobs().

• jobs_function (function | None, optional) – Routine to be performed per job.

  Default: None.

  When omitted and, hence, left set to the default value None, it will perform the default job handling routine, which goes as follows:

  func and args will be retrieved from the jobs queue and their combination func(*args) will get executed. Respectively, func and args correspond to instruction and pass_args of methods send() and add_to_queue().

  The default is sufficient when func corresponds to an I/O operation that is an one-way send, i.e. a write operation with optionally passed arguments, but without a reply from the device.

  Alternatively, you can pass it a reference to a user-supplied function performing an alternative job handling routine. This allows you to get creative and put, e.g., special string messages on the queue that decode into, e.g.,

  • multiple write operations to be executed as one block,
  • query operations whose return values can be acted upon accordingly,
  • extra data processing in between I/O operations.

  The function you supply must take two arguments, where the first argument is to be func and the second argument is to be args of type tuple. Both func and args will be retrieved from the jobs queue and passed onto your supplied function.

  Warning

  Neither directly change the GUI, nor print to the terminal from out of this function. Doing so might temporarily suspend the function and could mess with the timing stability of the worker. (You’re basically undermining the reason to have multithreading in the first place). That could be acceptable, though, when you need to print debug or critical error information to the terminal, but be aware about this warning.

  Instead, connect to QDeviceIO.signal_jobs_updated() from out of the main/GUI thread to instigate changes to the terminal/GUI when needed.

  Example:

  def my_jobs_function(func, args):
      if func == "query_id?":
          # Query the device for its identity string
          [success, ans_str] = dev.query("id?")
          # And store the reply 'ans_str' in another variable
          # at a higher scope or do stuff with it here.
      else:
          # Default job handling where, e.g.
          # func = dev.write
          # args = ("toggle LED",)
          func(*args)
  

• debug (bool, optional) – Print debug info to the terminal? Warning: Slow! Do not leave on unintentionally.

  Default: False.

• **kwargs – All remaining keyword arguments will be passed onto inherited class QObject.

Attributes:

qdev

Reference to the parent QDeviceIO class instance.

Type:QDeviceIO

dev

Reference to the user-supplied device class instance containing I/O methods, automatically set when calling QDeviceIO.create_worker_jobs(). It is a shorthand for self.qdev.dev.

Type:object | None

jobs_function

See the similarly named initialization parameter.

Type:function | None

Methods

Worker_jobs.send(instruction, pass_args=())

See the description at QDeviceIO.send().

This method can be called from another thread.

Worker_jobs.add_to_queue(instruction, pass_args=())

See the description at QDeviceIO.add_to_jobs_queue().

This method can be called from another thread.

Worker_jobs.process_queue()

See the description at QDeviceIO.process_jobs_queue().

This method can be called from another thread.