MythTV  master
Static Public Member Functions | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
PreviewGeneratorQueue Class Reference

This class implements a queue of preview generation requests. More...

#include <previewgeneratorqueue.h>

Inheritance diagram for PreviewGeneratorQueue:
Inheritance graph
[legend]
Collaboration diagram for PreviewGeneratorQueue:
Collaboration graph
[legend]

Static Public Member Functions

static void CreatePreviewGeneratorQueue (PreviewGenerator::Mode mode, uint maxAttempts, std::chrono::seconds minBlockSeconds)
 Create the singleton queue of preview generators. More...
 
static void TeardownPreviewGeneratorQueue ()
 Destroy the singleton queue of preview generators. More...
 
static void GetPreviewImage (const ProgramInfo &pginfo, const QString &token)
 Submit a request for the generation of a preview image. More...
 
static void GetPreviewImage (const ProgramInfo &pginfo, QSize outputsize, const QString &outputfile, std::chrono::seconds time, long long frame, const QString &token)
 Submit a request for the generation of a preview image. More...
 
static void AddListener (QObject *listener)
 Request notifications when a preview event is generated. More...
 
static void RemoveListener (QObject *listener)
 Stop receiving notifications when a preview event is generated. More...
 
- Static Public Member Functions inherited from MThread
static void ThreadSetup (const QString &name)
 This is to be called on startup in those few threads that haven't been ported to MThread. More...
 
static void ThreadCleanup (void)
 This is to be called on exit in those few threads that haven't been ported to MThread. More...
 
static void Cleanup (void)
 This will print out all the running threads, call exit(1) on each and then wait up to 5 seconds total for all the threads to exit. More...
 
static void GetAllThreadNames (QStringList &list)
 
static void GetAllRunningThreadNames (QStringList &list)
 

Private Member Functions

 PreviewGeneratorQueue (PreviewGenerator::Mode mode, uint maxAttempts, std::chrono::seconds minBlockSeconds)
 
 ~PreviewGeneratorQueue () override
 Destroy the preview generation queue. More...
 
QString GeneratePreviewImage (ProgramInfo &pginfo, QSize size, const QString &outputfile, std::chrono::seconds time, long long frame, const QString &token)
 Generate a preview image for the specified program. More...
 
void GetInfo (const QString &key, uint &queue_depth, uint &token_cnt)
 
void SetPreviewGenerator (const QString &key, PreviewGenerator *g)
 Sets the PreviewGenerator for a specific file. More...
 
void IncPreviewGeneratorPriority (const QString &key, const QString &token)
 
void UpdatePreviewGeneratorThreads (void)
 As long as there are items in the queue, make sure we're running the maximum allowed number of preview generators. More...
 
bool IsGeneratingPreview (const QString &key) const
 Is a preview currently being generated for this key. More...
 
uint IncPreviewGeneratorAttempts (const QString &key)
 Increments and returns number of times we have started a PreviewGenerator to create this file. More...
 
void ClearPreviewGeneratorAttempts (const QString &key)
 Clears the number of times we have started a PreviewGenerator to create this file. More...
 
bool event (QEvent *e) override
 The event handler running on the preview generation thread. More...
 
void SendEvent (const ProgramInfo &pginfo, const QString &eventname, const QString &filename, const QString &token, const QString &msg, const QDateTime &dt)
 Send a message back to all objects that have requested creation of a specific preview. More...
 

Private Attributes

QSet< QObject * > m_listeners
 The set of all listeners that want messages when a preview request is queued or finishes. More...
 
QMutex m_lock
 The thread interlock for this data structure. More...
 
PreviewGenerator::Mode m_mode
 
PreviewMap m_previewMap
 A mapping from the generated preview name to the state information on the progress of generating the preview. More...
 
QMap< QString, QString > m_tokenToKeyMap
 A mapping from requestor tokens to internal keys. More...
 
QStringList m_queue
 The queue of previews to be generated. More...
 
uint m_running {0}
 The number of threads currently generating previews. More...
 
uint m_maxThreads {2}
 The maximum number of threads that may concurrently generate previews. More...
 
uint m_maxAttempts
 How many times total will the code attempt to generate a preview for a specific file, before giving up and ignoring all future requests. More...
 
std::chrono::seconds m_minBlockSeconds
 How long after a failed preview generation attempt will the code ignore subsequent requests. More...
 

Static Private Attributes

static PreviewGeneratorQueues_pgq = nullptr
 The singleton queue. More...
 

Additional Inherited Members

- Public Member Functions inherited from MThread
 MThread (const QString &objectName)
 Standard constructor. More...
 
 MThread (const QString &objectName, QRunnable *runnable)
 Use this constructor if you want the default run() method to run the QRunnable's run() method instead of entering the Qt event loop. More...
 
virtual ~MThread ()
 
 MThread (const MThread &)=delete
 
MThreadoperator= (const MThread &)=delete
 
void RunProlog (void)
 Sets up a thread, call this if you reimplement run(). More...
 
void RunEpilog (void)
 Cleans up a thread's resources, call this if you reimplement run(). More...
 
QThread * qthread (void)
 Returns the thread, this will always return the same pointer no matter how often you restart the thread. More...
 
void setObjectName (const QString &name)
 
QString objectName (void) const
 
void setPriority (QThread::Priority priority)
 
QThread::Priority priority (void) const
 
bool isFinished (void) const
 
bool isRunning (void) const
 
void setStackSize (uint stackSize)
 
uint stackSize (void) const
 
void exit (int retcode=0)
 Use this to exit from the thread if you are using a Qt event loop. More...
 
void start (QThread::Priority p=QThread::InheritPriority)
 Tell MThread to start running the thread in the near future. More...
 
void terminate (void)
 Kill a thread unsafely. More...
 
void quit (void)
 calls exit(0) More...
 
bool wait (std::chrono::milliseconds time=std::chrono::milliseconds::max())
 Wait for the MThread to exit, with a maximum timeout. More...
 
- Protected Member Functions inherited from MThread
virtual void run (void)
 Runs the Qt event loop unless we have a QRunnable, in which case we run the runnable run instead. More...
 
int exec (void)
 Enters the qt event loop. call exit or quit to exit thread. More...
 
- Static Protected Member Functions inherited from MThread
static void setTerminationEnabled (bool enabled=true)
 
static void usleep (std::chrono::microseconds time)
 
template<typename R , typename P >
static std::enable_if_t< std::chrono::treat_as_floating_point< R >::value, void > usleep (std::chrono::duration< R, P > time)
 
- Protected Attributes inherited from MThread
MThreadInternalm_thread {nullptr}
 
QRunnable * m_runnable {nullptr}
 
bool m_prologExecuted {true}
 
bool m_epilogExecuted {true}
 

Detailed Description

This class implements a queue of preview generation requests.

It has a rendezvous mechanism (messaging) so that the actual generation can run in it own separate thread and not affect the program main thread. It also implements an API for starting and retrieving information about requests. This queue is effectively a singleton, although the code does not enforce that. It is expected that the queue will be created at application startup, and torn down at application shutdown.

Preview requestors use tokens to refer to their request. These have no meaning to the preview generator code, and are mapped to keys which are the used internally for indexing. Multiple caller tokens can map to the same internal key. (I.E. A preview for a program was requested from two different parts of the code.)

Definition at line 68 of file previewgeneratorqueue.h.

Constructor & Destructor Documentation

◆ PreviewGeneratorQueue()

PreviewGeneratorQueue::PreviewGeneratorQueue ( PreviewGenerator::Mode  mode,
uint  maxAttempts,
std::chrono::seconds  minBlockSeconds 
)
private

Definition at line 82 of file previewgeneratorqueue.cpp.

Referenced by CreatePreviewGeneratorQueue().

◆ ~PreviewGeneratorQueue()

PreviewGeneratorQueue::~PreviewGeneratorQueue ( )
overrideprivate

Destroy the preview generation queue.

This function doesn't directly destroy the PreviewGenState objects, but marks them for later destruction by the thread(s) that created them.

Note
Never directly destroy this object. Call the TeardownPreviewGeneratorQueue function instead.

Definition at line 107 of file previewgeneratorqueue.cpp.

Member Function Documentation

◆ CreatePreviewGeneratorQueue()

void PreviewGeneratorQueue::CreatePreviewGeneratorQueue ( PreviewGenerator::Mode  mode,
uint  maxAttempts,
std::chrono::seconds  minBlockSeconds 
)
static

Create the singleton queue of preview generators.

This should be called once at program start-up. All generation requests on this queue will will be created with the maxAttempts and minBlockSeconds parameters supplied here.

Parameters
[in]modeLocal or Remote (or both)
[in]maxAttemptsHow many times total will the code attempt to generate a preview for a specific file, before giving up and ignoring all future requests.
[in]minBlockSecondsHow long after a failed preview generation attempt will the code ignore subsequent requests.

Definition at line 42 of file previewgeneratorqueue.cpp.

Referenced by main(), and MainServer::MainServer().

◆ TeardownPreviewGeneratorQueue()

void PreviewGeneratorQueue::TeardownPreviewGeneratorQueue ( )
static

Destroy the singleton queue of preview generators.

This should be called once at program shutdown. It handles stopping all the running threads before deleting the actual PreviewGeneratorQueue object.

Definition at line 55 of file previewgeneratorqueue.cpp.

Referenced by main(), and MainServer::Stop().

◆ GetPreviewImage() [1/2]

static void PreviewGeneratorQueue::GetPreviewImage ( const ProgramInfo pginfo,
const QString &  token 
)
inlinestatic

Submit a request for the generation of a preview image.

This information will be packaged up into an event and sent over to the worker thread that generates previews.

Parameters
[in]pginfoGenerate the image for this program.
[in]tokenA user specified value used to match up this request with the response from the backend, and as a key for some indexing. A token isn't required, but is strongly suggested.

Definition at line 89 of file previewgeneratorqueue.h.

Referenced by PBHEventHandler::event(), TVRec::FinishedRecording(), MainServer::HandleGenPreviewPixmap(), and TVRec::SwitchRecordingRingBuffer().

◆ GetPreviewImage() [2/2]

void PreviewGeneratorQueue::GetPreviewImage ( const ProgramInfo pginfo,
QSize  outputsize,
const QString &  outputfile,
std::chrono::seconds  time,
long long  frame,
const QString &  token 
)
static

Submit a request for the generation of a preview image.

This information will be packaged up into an event and sent over to the worker thread that generates previews.

Parameters
[in]pginfoGenerate the image for this program.
[in]outputsizeGenerate a preview image of these dimensions. If this is not specified the generated image will be the same size as the program.
[in]outputfileUse this specific filename for the preview image. If empty, a default name will be created based on the program information.
[in]timeAn offset from the start of the program in seconds. This field has priority. If it is set to -1s then seekframe will be used.
[in]frameAn offset from the start of the program in frames.
[in]tokenA user specified value used to match up this request with the response from the backend, and as a key for some indexing. A token isn't required, but is strongly suggested.

Definition at line 143 of file previewgeneratorqueue.cpp.

◆ AddListener()

void PreviewGeneratorQueue::AddListener ( QObject *  listener)
static

Request notifications when a preview event is generated.

These will be MythEvent messages, and will be one of PREVIEW_QUEUED, PREVIEW_FAILED or PREVIEW_SUCCESS.

Parameters
[in]listenerThe object to receive events.

Definition at line 189 of file previewgeneratorqueue.cpp.

Referenced by PlaybackBox::Load(), and MainServer::MainServer().

◆ RemoveListener()

void PreviewGeneratorQueue::RemoveListener ( QObject *  listener)
static

Stop receiving notifications when a preview event is generated.

This object will no longer receive PREVIEW_QUEUED, PREVIEW_FAILED, or PREVIEW_SUCCESS events.

Parameters
[in]listenerThe object that should no longer receive events.

Definition at line 205 of file previewgeneratorqueue.cpp.

Referenced by MainServer::Stop(), and PlaybackBox::~PlaybackBox().

◆ GeneratePreviewImage()

QString PreviewGeneratorQueue::GeneratePreviewImage ( ProgramInfo pginfo,
QSize  size,
const QString &  outputfile,
std::chrono::seconds  time,
long long  frame,
const QString &  token 
)
private

Generate a preview image for the specified program.

This function will find an existing preview image for a program, or schedules the generation of a preview image if it doesn't exist. If any of the arguments that could affect the generated image (size, outputfile, time offset) have been specified, then a new image will always be generated.

Parameters
pginfoGenerate the image for this program.
sizeGenerate a preview image of these dimensions. If this is not specified the generated image will be the same size as the program.
outputfileUse this specific filename for the preview image. If empty, a default name will be created based on the program information.
timeAn offset from the start of the program in seconds. This field has priority. If it is set to -1s then seekframe will be used.
framesAn offset from the start of the program in frames.
tokenAn arbitrary string value used to match up this request with the response from the backend, and as a key for some indexing. A token isn't required, but is strongly suggested.
Returns
The filename of the preview images. This will be null if the preview does not yet or will never exist.
Note
This function will always send one of three events. If the program has been marked for deletion, this function will send a PREVIEW_FAILED event. If a preview already exists, the function sends a PREVIEW_SUCCESS event. Otherwise it sends a PREVIEW_QUEUED event.
Warning
This function should only be called from the preview generation thread.

Definition at line 427 of file previewgeneratorqueue.cpp.

Referenced by event().

◆ GetInfo()

void PreviewGeneratorQueue::GetInfo ( const QString &  key,
uint queue_depth,
uint token_cnt 
)
private
Parameters
[in]keyThe name of the specific preview being generated. Keys are generated internally to this file and are in the form <basenane>_<w>x<h>_<offset>.
[out]queue_depthThe total number of items in the queue to be processed. This number does not include previews that are currently in process of being generated.
[out]token_cntThe number of listeners that are waiting for this preview to be generated.

Definition at line 618 of file previewgeneratorqueue.cpp.

Referenced by GeneratePreviewImage().

◆ SetPreviewGenerator()

void PreviewGeneratorQueue::SetPreviewGenerator ( const QString &  key,
PreviewGenerator g 
)
private

Sets the PreviewGenerator for a specific file.

Parameters
[in]keyThe name of the specific preview being generated. Keys are generated internally to this file and are in the form <basenane>_<w>x<h>_<offset>.
[in]g

Definition at line 684 of file previewgeneratorqueue.cpp.

Referenced by GeneratePreviewImage().

◆ IncPreviewGeneratorPriority()

void PreviewGeneratorQueue::IncPreviewGeneratorPriority ( const QString &  key,
const QString &  token 
)
private
Parameters
[in]keyThe name of the specific preview being generated. Keys are generated internally to this file and are in the form <basenane>_<w>x<h>_<offset>.
[in]token

Definition at line 634 of file previewgeneratorqueue.cpp.

Referenced by GeneratePreviewImage(), and SetPreviewGenerator().

◆ UpdatePreviewGeneratorThreads()

void PreviewGeneratorQueue::UpdatePreviewGeneratorThreads ( void  )
private

As long as there are items in the queue, make sure we're running the maximum allowed number of preview generators.

Definition at line 658 of file previewgeneratorqueue.cpp.

Referenced by event(), and GeneratePreviewImage().

◆ IsGeneratingPreview()

bool PreviewGeneratorQueue::IsGeneratingPreview ( const QString &  key) const
private

Is a preview currently being generated for this key.

This returns true if a PreviewGenerator has been started to create this preview. It also returns true if the previous generation attempt failed, and we're still in the blocking interval before another attempt is allowed.

Parameters
[in]keyThe name of the specific preview being generated. Keys are generated internally to this file and are in the form <basenane>_<w>x<h>_<offset>.
Returns
True if generating a preview or blocked. False if a new attempt is allowed.

Definition at line 731 of file previewgeneratorqueue.cpp.

Referenced by GeneratePreviewImage().

◆ IncPreviewGeneratorAttempts()

uint PreviewGeneratorQueue::IncPreviewGeneratorAttempts ( const QString &  key)
private

Increments and returns number of times we have started a PreviewGenerator to create this file.

Parameters
[in]keyThe name of the specific preview being generated. Keys are generated internally to this file and are in the form <basenane>_<w>x<h>_<offset>.

Definition at line 753 of file previewgeneratorqueue.cpp.

Referenced by GeneratePreviewImage().

◆ ClearPreviewGeneratorAttempts()

void PreviewGeneratorQueue::ClearPreviewGeneratorAttempts ( const QString &  key)
private

Clears the number of times we have started a PreviewGenerator to create this file.

This also resets the the blocking information so that the next preview request for this file may run immediately.

Parameters
[in]keyThe name of the specific preview being generated. Keys are generated internally to this file and are in the form <basenane>_<w>x<h>_<offset>.

Definition at line 768 of file previewgeneratorqueue.cpp.

Referenced by GeneratePreviewImage().

◆ event()

bool PreviewGeneratorQueue::event ( QEvent *  e)
overrideprivate

The event handler running on the preview generation thread.

Parameters
[in]eThe received message. This should be one of the messages GET_PREVIEW, PREVIEW_SUCCESS, or PREVIEW_FAILED.
Warning
This function should only be called from the preview generation thread.
Bug:
This function appears to incorrectly compute the value of lastBlockTime. The call to std::max() will correctly ensure that if the old value of lastBlockTime is zero, that the new time for the first "retry" will be two. The problem is that all subsequent "retries" will also be limited to two, so there is no increasing back off interval like it appears was intended.

Definition at line 230 of file previewgeneratorqueue.cpp.

◆ SendEvent()

void PreviewGeneratorQueue::SendEvent ( const ProgramInfo pginfo,
const QString &  eventname,
const QString &  filename,
const QString &  token,
const QString &  msg,
const QDateTime &  dt 
)
private

Send a message back to all objects that have requested creation of a specific preview.

Parameters
[in]pginfoThe program info structure from which the preview was generated.
[in]eventnameThe name of the event being sent to all listeners. This will always be one of PREVIEW_FAILED, PREVIEW_QUEUED, or PREVIEW_SUCCESS.
[in]filenameFor a SUCCESS message, this is the name of the newly generated preview file. For a QUEUED message, this is an empty string. For a FAILED message, this will be the internal key value.
[in]tokenThe token specified by the listener when it requested the preview generation.
[in]msgA text string giving more information about the processing of the event.
[in]dtFor a PREVIEW_SUCCESS message, this is the the last modified time of the preview file. For the other messages, this is a null datetime.

Definition at line 371 of file previewgeneratorqueue.cpp.

Referenced by GeneratePreviewImage().

Member Data Documentation

◆ s_pgq

PreviewGeneratorQueue * PreviewGeneratorQueue::s_pgq = nullptr
staticprivate

The singleton queue.

Allows all the static functions to find the queue.

Definition at line 130 of file previewgeneratorqueue.h.

Referenced by AddListener(), CreatePreviewGeneratorQueue(), GetPreviewImage(), RemoveListener(), and TeardownPreviewGeneratorQueue().

◆ m_listeners

QSet<QObject*> PreviewGeneratorQueue::m_listeners
private

The set of all listeners that want messages when a preview request is queued or finishes.

Definition at line 133 of file previewgeneratorqueue.h.

Referenced by AddListener(), event(), RemoveListener(), and SendEvent().

◆ m_lock

QMutex PreviewGeneratorQueue::m_lock
mutableprivate

◆ m_mode

PreviewGenerator::Mode PreviewGeneratorQueue::m_mode
private

Definition at line 137 of file previewgeneratorqueue.h.

Referenced by GeneratePreviewImage().

◆ m_previewMap

PreviewMap PreviewGeneratorQueue::m_previewMap
private

A mapping from the generated preview name to the state information on the progress of generating the preview.

Definition at line 140 of file previewgeneratorqueue.h.

Referenced by ClearPreviewGeneratorAttempts(), event(), GetInfo(), IncPreviewGeneratorAttempts(), IncPreviewGeneratorPriority(), IsGeneratingPreview(), SetPreviewGenerator(), UpdatePreviewGeneratorThreads(), and ~PreviewGeneratorQueue().

◆ m_tokenToKeyMap

QMap<QString,QString> PreviewGeneratorQueue::m_tokenToKeyMap
private

A mapping from requestor tokens to internal keys.

Definition at line 142 of file previewgeneratorqueue.h.

Referenced by event(), IncPreviewGeneratorPriority(), and SetPreviewGenerator().

◆ m_queue

QStringList PreviewGeneratorQueue::m_queue
private

The queue of previews to be generated.

The next item to be processed is the one at the back of the queue.

Definition at line 145 of file previewgeneratorqueue.h.

Referenced by GetInfo(), IncPreviewGeneratorPriority(), and UpdatePreviewGeneratorThreads().

◆ m_running

uint PreviewGeneratorQueue::m_running {0}
private

The number of threads currently generating previews.

Definition at line 147 of file previewgeneratorqueue.h.

Referenced by event(), and UpdatePreviewGeneratorThreads().

◆ m_maxThreads

uint PreviewGeneratorQueue::m_maxThreads {2}
private

The maximum number of threads that may concurrently generate previews.

Definition at line 150 of file previewgeneratorqueue.h.

Referenced by PreviewGeneratorQueue(), and UpdatePreviewGeneratorThreads().

◆ m_maxAttempts

uint PreviewGeneratorQueue::m_maxAttempts
private

How many times total will the code attempt to generate a preview for a specific file, before giving up and ignoring all future requests.

Definition at line 154 of file previewgeneratorqueue.h.

Referenced by GeneratePreviewImage().

◆ m_minBlockSeconds

std::chrono::seconds PreviewGeneratorQueue::m_minBlockSeconds
private

How long after a failed preview generation attempt will the code ignore subsequent requests.

Definition at line 157 of file previewgeneratorqueue.h.

Referenced by event().


The documentation for this class was generated from the following files: