Cache class. More...

Public Member Functions
void	mlt_cache_close (mlt_cache cache)
	Destroy a cache. More...

mlt_cache_item	mlt_cache_get (mlt_cache cache, void *object)
	Get a chunk of data from the cache. More...

mlt_frame	mlt_cache_get_frame (mlt_cache cache, mlt_position position)
	Get a frame from the cache. More...

int	mlt_cache_get_size (mlt_cache cache)
	Get the number of possible cache items. More...

mlt_cache	mlt_cache_init ()
	Create a new cache. More...

void *	mlt_cache_item_data (mlt_cache_item item, int *size)
	Get the data pointer from the cache item. More...

void	mlt_cache_purge (mlt_cache cache, void *object)
	Remove cache entries for an object. More...

void	mlt_cache_put (mlt_cache cache, void object, void data, int size, mlt_destructor destructor)
	Put a chunk of data in the cache. More...

void	mlt_cache_put_frame (mlt_cache cache, mlt_frame frame)
	Put a frame in the cache with audio and video. More...

void	mlt_cache_put_frame_audio (mlt_cache cache, mlt_frame frame)
	Put a frame in the cache with audio. More...

void	mlt_cache_put_frame_image (mlt_cache cache, mlt_frame frame)
	Put a frame in the cache with image. More...

void	mlt_cache_set_size (mlt_cache cache, int size)
	Set the number of items to cache. More...

Data Fields
void *	A [MAX_CACHE_SIZE]

mlt_properties	active
	a list of cache items some of which may no longer be in `current` but to which there are outstanding references More...

void *	B [MAX_CACHE_SIZE]

int	count
	the number of items currently in the cache More...

void **	current
	pointer to the current array of pointers More...

mlt_properties	garbage
	a list cache items pending release. More...

int	is_frames
	indicates if this cache is used to cache frames More...

pthread_mutex_t	mutex
	a mutex to prevent multi-threaded race conditions More...

int	size
	the maximum number of items permitted in the cache <= `MAX_CACHE_SIZE` More...

Private Member Functions
static void	cache_object_close (mlt_cache cache, void object, void data)
	Close a cache item given its parent object pointer. More...

static mlt_frame *	shuffle_get_frame (mlt_cache cache, mlt_position position)
	Shuffle the cache entries between the two arrays and return the frame for a position. More...

static void **	shuffle_get_hit (mlt_cache cache, void *object)
	Shuffle the cache entries between the two arrays and return the cache entry for an object. More...

Detailed Description

Cache class.

This is a utility class for implementing a Least Recently Used (LRU) cache of data blobs indexed by the address of some other object (e.g., a service). Instead of sorting and manipulating linked lists, it tries to be simple and elegant by copying pointers between two arrays of fixed size to shuffle the order of elements.

This class is useful if you have a service that wants to cache something somewhat large, but will not scale if there are many instances of the service. Of course, the service will need to know how to recreate the cached element if it gets flushed from the cache,

The most obvious examples are the pixbuf and qimage producers that cache their respective objects representing a picture read from a file. If the picture is no longer in the cache, it can simply re-read it from file. However, a picture is often repeated over many frames and makes sense to cache instead of continually reading, parsing, and decoding. On the other hand, you might want to load hundreds of pictures as individual producers, which would use a lot of memory if every picture is held in memory!

Member Function Documentation

◆ cache_object_close()

static void cache_object_close	(	mlt_cache	cache,
		void *	object,
		void *	data
	)

private

Close a cache item given its parent object pointer.

Parameters

cache	a cache
object	the object to which the data object belongs
data	the data object, which might be in the garbage list (optional)

◆ mlt_cache_close()

void mlt_cache_close ( mlt_cache cache )

Destroy a cache.

Parameters

cache the cache to destroy

◆ mlt_cache_get()

mlt_cache_item mlt_cache_get	(	mlt_cache	cache,
		void *	object
	)

Get a chunk of data from the cache.

Parameters

cache	a cache object
object	the object for which you are trying to locate the data

Returns: a mlt_cache_item if found or NULL if not found or has been flushed from the cache

◆ mlt_cache_get_frame()

mlt_frame mlt_cache_get_frame	(	mlt_cache	cache,
		mlt_position	position
	)

Get a frame from the cache.

You must call mlt_frame_close() on the frame you receive from this.

Parameters

cache	a cache object
position	the position of the frame that you want

Returns: a frame if found or NULL if not found or has been flushed from the cache

See also: mlt_frame_put_frame

◆ mlt_cache_get_size()

int mlt_cache_get_size ( mlt_cache cache )

Get the number of possible cache items.

Parameters

cache the cache to check

Returns: the current maximum size of the cache

◆ mlt_cache_init()

mlt_cache mlt_cache_init ( )

Create a new cache.

The default size is DEFAULT_CACHE_SIZE.

Returns: a new cache or NULL if there was an error

◆ mlt_cache_item_data()

void * mlt_cache_item_data	(	mlt_cache_item	item,
		int *	size
	)

Get the data pointer from the cache item.

Parameters

	item	a cache item
[out]	size	the number of bytes pointed at, if supplied when putting the data into the cache

Returns: the data pointer

◆ mlt_cache_purge()

void mlt_cache_purge	(	mlt_cache	cache,
		void *	object
	)

Remove cache entries for an object.

Parameters

cache	a cache
object	the object that owns the cached data

◆ mlt_cache_put()

void mlt_cache_put	(	mlt_cache	cache,
		void *	object,
		void *	data,
		int	size,
		mlt_destructor	destructor
	)

Put a chunk of data in the cache.

This function and mlt_cache_get() are not scalable with a large volume of unique object parameter values. Therefore, it does not make sense to use it for a frame/image cache using the frame position for object. Instead, use mlt_cache_put_frame() for that.

Parameters

cache	a cache object
object	the object to which this data belongs
data	an opaque pointer to the data to cache
size	the size of the data in bytes
destructor	a pointer to a function that can destroy or release a reference to the data.

◆ mlt_cache_put_frame()

void mlt_cache_put_frame	(	mlt_cache	cache,
		mlt_frame	frame
	)

Put a frame in the cache with audio and video.

Unlike mlt_cache_put() this version is more suitable for caching frames and their data - like images. However, this version does not use reference counting and garbage collection. Rather, frames are cloned with deep copy to avoid those things.

Parameters

cache	a cache object
frame	the frame to cache

See also: mlt_frame_get_frame

◆ mlt_cache_put_frame_audio()

void mlt_cache_put_frame_audio	(	mlt_cache	cache,
		mlt_frame	frame
	)

Put a frame in the cache with audio.

Unlike mlt_cache_put() this version is more suitable for caching frames and their data - like images. However, this version does not use reference counting and garbage collection. Rather, frames are cloned with deep copy to avoid those things.

Parameters

cache	a cache object
frame	the frame to cache

See also: mlt_frame_get_frame

◆ mlt_cache_put_frame_image()

void mlt_cache_put_frame_image	(	mlt_cache	cache,
		mlt_frame	frame
	)

Put a frame in the cache with image.

Unlike mlt_cache_put() this version is more suitable for caching frames and their data - like images. However, this version does not use reference counting and garbage collection. Rather, frames are cloned with deep copy to avoid those things.

Parameters

cache	a cache object
frame	the frame to cache

See also: mlt_frame_get_frame

◆ mlt_cache_set_size()

void mlt_cache_set_size	(	mlt_cache	cache,
		int	size
	)

Set the number of items to cache.

This must be called before using the cache. The size can not be more than MAX_CACHE_SIZE.

Parameters

cache	the cache to adjust
size	the new size of the cache

◆ shuffle_get_frame()

static mlt_frame * shuffle_get_frame	(	mlt_cache	cache,
		mlt_position	position
	)

private

Shuffle the cache entries between the two arrays and return the frame for a position.

Parameters

cache	a cache object
position	the position of the frame that you want

Returns: a frame if there was a hit or NULL for a miss

◆ shuffle_get_hit()

static void ** shuffle_get_hit	(	mlt_cache	cache,
		void *	object
	)

private

Shuffle the cache entries between the two arrays and return the cache entry for an object.

Parameters

cache	a cache object
object	the object that owns the cached data

Returns: a cache entry if there was a hit or NULL for a miss

Field Documentation

◆ A

void* mlt_cache_s::A[MAX_CACHE_SIZE]

◆ active

mlt_properties mlt_cache_s::active

a list of cache items some of which may no longer be in current but to which there are outstanding references

◆ B

void* mlt_cache_s::B[MAX_CACHE_SIZE]

◆ count

int mlt_cache_s::count

the number of items currently in the cache

◆ current

void** mlt_cache_s::current

pointer to the current array of pointers

◆ garbage

mlt_properties mlt_cache_s::garbage

a list cache items pending release.

A cache item is copied to this list when it is updated but there are outstanding references to the old data object.

◆ is_frames

int mlt_cache_s::is_frames

indicates if this cache is used to cache frames

◆ mutex

pthread_mutex_t mlt_cache_s::mutex

a mutex to prevent multi-threaded race conditions

◆ size

int mlt_cache_s::size

the maximum number of items permitted in the cache <= MAX_CACHE_SIZE

The documentation for this struct was generated from the following file:

mlt_cache.c

Public Member Functions

Data Fields

Private Member Functions

Detailed Description

Member Function Documentation

◆ cache_object_close()

◆ mlt_cache_close()

◆ mlt_cache_get()

◆ mlt_cache_get_frame()

◆ mlt_cache_get_size()

◆ mlt_cache_init()

◆ mlt_cache_item_data()

◆ mlt_cache_purge()

◆ mlt_cache_put()

◆ mlt_cache_put_frame()

◆ mlt_cache_put_frame_audio()

◆ mlt_cache_put_frame_image()

◆ mlt_cache_set_size()

◆ shuffle_get_frame()

◆ shuffle_get_hit()

Field Documentation

◆ A

◆ active

◆ B

◆ count

◆ current

◆ garbage

◆ is_frames

◆ mutex

◆ size