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

#include <libmythtv/previewgeneratorqueue.h>

Inheritance diagram for PreviewGeneratorQueue:

Collaboration diagram for PreviewGeneratorQueue:

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 PreviewGeneratorQueue *	s_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

MThread &	operator= (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
MThreadInternal *	m_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]	mode	Local or Remote (or both)
[in]	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.
[in]	minBlockSeconds	How 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]	pginfo	Generate the image for this program.
[in]	token	A 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]	pginfo	Generate the image for this program.
[in]	outputsize	Generate a preview image of these dimensions. If this is not specified the generated image will be the same size as the program.
[in]	outputfile	Use this specific filename for the preview image. If empty, a default name will be created based on the program information.
[in]	time	An 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]	frame	An offset from the start of the program in frames.
[in]	token	A 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] listener The 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] listener The 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

pginfo	Generate the image for this program.
size	Generate a preview image of these dimensions. If this is not specified the generated image will be the same size as the program.
outputfile	Use this specific filename for the preview image. If empty, a default name will be created based on the program information.
time	An offset from the start of the program in seconds. This field has priority. If it is set to -1s then seekframe will be used.
frames	An offset from the start of the program in frames.
token	An 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]	key	The 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_depth	The 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_cnt	The 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]	key	The 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]	key	The 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] key The 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] key The 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] key The 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] e The 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]	pginfo	The program info structure from which the preview was generated.
[in]	eventname	The name of the event being sent to all listeners. This will always be one of PREVIEW_FAILED, PREVIEW_QUEUED, or PREVIEW_SUCCESS.
[in]	filename	For 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]	token	The token specified by the listener when it requested the preview generation.
[in]	msg	A text string giving more information about the processing of the event.
[in]	dt	For 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

The thread interlock for this data structure.

Definition at line 135 of file previewgeneratorqueue.h.

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

◆ 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:

mythtv/libs/libmythtv/previewgeneratorqueue.h
mythtv/libs/libmythtv/previewgeneratorqueue.cpp

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PreviewGeneratorQueue()

◆ ~PreviewGeneratorQueue()

Member Function Documentation

◆ CreatePreviewGeneratorQueue()

◆ TeardownPreviewGeneratorQueue()

◆ GetPreviewImage() [1/2]

◆ GetPreviewImage() [2/2]

◆ AddListener()

◆ RemoveListener()

◆ GeneratePreviewImage()

◆ GetInfo()

◆ SetPreviewGenerator()

◆ IncPreviewGeneratorPriority()

◆ UpdatePreviewGeneratorThreads()

◆ IsGeneratingPreview()

◆ IncPreviewGeneratorAttempts()

◆ ClearPreviewGeneratorAttempts()

◆ event()

◆ SendEvent()

Member Data Documentation

◆ s_pgq

◆ m_listeners

◆ m_lock

◆ m_mode

◆ m_previewMap

◆ m_tokenToKeyMap

◆ m_queue

◆ m_running

◆ m_maxThreads

◆ m_maxAttempts

◆ m_minBlockSeconds