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, uint 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, QString token)
 Submit a request for the generation of a preview image. More...
 
static void GetPreviewImage (const ProgramInfo &, const QSize &, const QString &outputfile, long long time, bool in_seconds, QString token)
 Submit a request for the generation of a preview image. More...
 
static void AddListener (QObject *)
 Request notifications when a preview event is generated. More...
 
static void RemoveListener (QObject *)
 Stop receiving notifications when a preview event is generated. More...
 
- Static Public Member Functions inherited from MThread
static void ThreadSetup (const QString &)
 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, uint minBlockSeconds)
 
 ~PreviewGeneratorQueue ()
 Destroy the preview generation queue. More...
 
QString GeneratePreviewImage (ProgramInfo &pginfo, const QSize &, const QString &outputfile, long long time, bool in_seconds, QString token)
 Generate a preview image for the specified program. More...
 
void GetInfo (const QString &key, uint &queue_depth, uint &preview_tokens)
 
void SetPreviewGenerator (const QString &key, PreviewGenerator *g)
 Sets the PreviewGenerator for a specific file. More...
 
void IncPreviewGeneratorPriority (const QString &key, 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 &fn, 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
 The number of threads currently generating previews. More...
 
uint m_maxThreads
 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...
 
uint 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 ()
 
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=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 (unsigned long time=ULONG_MAX)
 Wait for the MThread to exit, with a maximum timeout. More...
 
- Static Public Attributes inherited from MThread
static const int kDefaultStartTimeout
 
- 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 sleep (unsigned long time)
 
static void msleep (unsigned long time)
 
static void usleep (unsigned long time)
 
- Protected Attributes inherited from MThread
MThreadInternalm_thread
 
QRunnable * m_runnable
 
bool m_prolog_executed
 
bool m_epilog_executed
 

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 69 of file previewgeneratorqueue.h.

Constructor & Destructor Documentation

◆ PreviewGeneratorQueue()

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

Definition at line 83 of file previewgeneratorqueue.cpp.

Referenced by CreatePreviewGeneratorQueue().

◆ ~PreviewGeneratorQueue()

PreviewGeneratorQueue::~PreviewGeneratorQueue ( )
private

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 109 of file previewgeneratorqueue.cpp.

Member Function Documentation

◆ CreatePreviewGeneratorQueue()

void PreviewGeneratorQueue::CreatePreviewGeneratorQueue ( PreviewGenerator::Mode  mode,
uint  maxAttempts,
uint  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 43 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 56 of file previewgeneratorqueue.cpp.

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

◆ GetPreviewImage() [1/2]

static void PreviewGeneratorQueue::GetPreviewImage ( const ProgramInfo pginfo,
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 90 of file previewgeneratorqueue.h.

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

◆ GetPreviewImage() [2/2]

void PreviewGeneratorQueue::GetPreviewImage ( const ProgramInfo pginfo,
const QSize &  outputsize,
const QString &  outputfile,
long long  time,
bool  in_seconds,
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. This can be seconds or frames. (See the next argument.)
[in]in_secondsIf true, the 'time' offset is in seconds. If false, the offset is 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 145 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 183 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 199 of file previewgeneratorqueue.cpp.

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

◆ GeneratePreviewImage()

QString PreviewGeneratorQueue::GeneratePreviewImage ( ProgramInfo pginfo,
const QSize &  size,
const QString &  outputfile,
long long  time,
bool  in_seconds,
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. This can be seconds or frames. (See the next argument.)
in_secondsIf true, the 'time' offset is in seconds. If false, the offset is 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 415 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 602 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 668 of file previewgeneratorqueue.cpp.

Referenced by GeneratePreviewImage().

◆ IncPreviewGeneratorPriority()

void PreviewGeneratorQueue::IncPreviewGeneratorPriority ( const QString &  key,
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 618 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 642 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 715 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 737 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 752 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 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 224 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 358 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 131 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 134 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 138 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 141 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 143 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 146 of file previewgeneratorqueue.h.

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

◆ m_running

uint PreviewGeneratorQueue::m_running
private

The number of threads currently generating previews.

Definition at line 148 of file previewgeneratorqueue.h.

Referenced by event(), and UpdatePreviewGeneratorThreads().

◆ m_maxThreads

uint PreviewGeneratorQueue::m_maxThreads
private

The maximum number of threads that may concurrently generate previews.

Definition at line 151 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 155 of file previewgeneratorqueue.h.

Referenced by GeneratePreviewImage().

◆ m_minBlockSeconds

uint PreviewGeneratorQueue::m_minBlockSeconds
private

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

Definition at line 158 of file previewgeneratorqueue.h.

Referenced by event().


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