Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SQLEngine::Record::CacUser)Contributed Perl DocumenSQLEngine::Record::Cache(3)

NAME
       DBIx::SQLEngine::Record::Cache -	Avoid Repeated Selects

SYNOPSIS
       Setup: Several ways to create a class.

	 my $sqldb = DBIx::SQLEngine->new( ... );

	 $class_name = $sqldb->record_class( $table_name, undef, 'Cache' );

	 $sqldb->record_class( $table_name, 'My::Record', 'Cache' );

	 package My::Record;
	 use DBIx::SQLEngine::Record::Class '-isasubclass', 'Cache';
	 My::Record->table( $sqldb->table($table_name) );

       Cache: Uses Cache::Cache	interface.

	 $class_name->use_cache_style('simple');

	 # requires Cache::FastMemoryCache
	 $class_name->use_cache_style('active');

	 use Cache::Cache;
	 $class_name->cache_cache( $my_cache_cache_object );

       Basics: Layered over superclass.

	 # Fetches from	cache if it's been seen	before
	 $record = $class_name->fetch_record( $primary_key );

	 # Fetches from	cache if we've run this	query before
	 @records = $class_name->fetch_select(%clauses)->records;

	 # Clears cache	so it's	seen by	next select query
	 $record->insert_record();

	 # Clears cache	so it's	seen by	next select query
	 $record->update_record();

	 # Clears cache	so it's	seen by	next select query
	 $record->delete_record();

DESCRIPTION
       This package provides a caching layer for DBIx::SQLEngine::Record
       objects.

       Don't use this module directly; instead,	pass its name as a trait when
       you create a new	record class. This package provides a multiply-
       composable collection of	functionality for Record classes. It is
       combined	with the base class and	other traits by
       DBIx::SQLEngine::Record::Class.

CACHE INTERFACE
   Cache Configuration
       cache_cache()
	     $record_class->cache_cache() : $cache_cache
	     $record_class->cache_cache( $cache_cache )

	   Gets	or sets	the cache object associated with this record class.

	   If no cache has been	set for	a given	class, no caching is
	   performed.

       Cache Object Requirements: This package in intended to work with	cache
       object that use the Cache::Cache	interface. However, any	package	which
       support the limited cache interface used	by this	package	should be
       sufficient.

       Two small classes are included that support this	interface; see
       DBIx::SQLEngine::Cache::TrivialCache and
       DBIx::SQLEngine::Cache::BasicCache.

       The following methods are used

	   Constructor.

	   get_namespace()

	   Used	to differentiate one cache object from another.

	   get()

	   Fetch a value from the cache, if it is present.

	   set()

	   Set a value in the cache.

	   clear()

	   Clear some or all values in the cache.

   Cache Operations
       cache_key()
	     $record_class->cache_key( $key ) :	$string_value
	     $record_class->cache_key( \@key ) : $string_value
	     $record_class->cache_key( \%key ) : $string_value

	   Returns the string value to be used as a cache key. The argument
	   may be an existing string, a	reference to a shallow array whose
	   elements will be joined with	"\0/\0", or any	other reference	value
	   which will be stringified by	Storable.

       cache_get()
	     $record_class->cache_get( $key ) :	$value
	     $record_class->cache_get( $key ) :	( $value, $updater_code_ref )

	   Returns the cached value associated with this key, if any. If
	   called in a list context, also returns a reference to a subroutine
	   which will save a new value for that	key.

       cache_set()
	     $record_class->cache_set( $key, $value )

	   Caches this value under the provided	key.

       cache_get_set()
	     $record_class->cache_get_set( $key, $code_ref, @args ) : $value

	   Returns the curent value provided by	a cache_get on the provided
	   key,	or if it is undefined, invokes the subroutine reference	with
	   any additional arguments provided, and saves	the subroutine's
	   return value	as the cached value.

       cache_clear()
	     $record_class->cache_clear()
	     $record_class->cache_clear( $key )

	   Clear all values from the cache, or just those associated with the
	   given key.

   Cache Logging
       CacheLogging()
	     $record_class->CacheLogging() : $level
	     $record_class->CacheLogging( $level )

	   Sets	the logging level associated with a given class.

       cache_log_operation()
	     $record_class->cache_log_operation( $cache, $operation, $key )

	   Does	nothing	unless a CacheLogging level is set for this class.

	   Uses	warn() to print	a message to the error log, including the key
	   string used,	and the	operation, which will be one of	"hit", "miss",
	   "write", and	"clear".

	   If the level	is greater than	one, the message will also include a
	   history of prior operations on this key.

   Cache Styles
       define_cache_styles()
	     DBIx::SQLEngine->define_cache_styles( $name, $code_ref )
	     DBIx::SQLEngine->define_cache_styles( %names_and_code_refs	)

	   Define a named caching style. The code ref supplied for each	name
	   should create and return an object from the Cache::Cache hierarchy,
	   or another caching class which supports the interface described in
	   the "Cache Object Requirements" section above.

       cache_styles()
	     DBIx::SQLEngine->cache_styles() : %names_and_info
	     DBIx::SQLEngine->cache_styles( $name ) : $info
	     DBIx::SQLEngine->cache_styles( \@names ) :	@info
	     DBIx::SQLEngine->cache_styles( $name, $info, ... )
	     DBIx::SQLEngine->cache_styles( \%names_and_info )

	   Accessor for	global hash mapping cache names	to initialization
	   subroutines.

       use_cache_style()
	     $class_name->use_cache_style( $cache_style_name )
	     $class_name->use_cache_style( $cache_style_name, @options )

	   Uses	the named caching definition to	create a new cache object, and
	   associates it with the given	class.

	   Use one of the predefined caching styles described in the "Default
	   Caching Styles" section below, or define your own cache styles with
	   define_cache_styles.

       Default Caching Styles: The following cache styles are predefined.
       Except for 'simple', using any of these styles will require
       installation of the Cache::Cache	distribution.

       'simple'
	   Uses	DBIx::SQLEngine::Cache::TrivialCache.

       'live'
	   Uses	Cache::FastMemoryCache with a default expiration time of 1
	   seconds.

       'active'
	   Uses	Cache::FastMemoryCache with a default expiration time of 5
	   seconds.

       'stable'
	   Uses	Cache::FastMemoryCache with a default expiration time of 30
	   seconds.

       'file'
	   Uses	Cache::FileCache with a	default	expiration time	of 30 seconds.

       Examples:

       o

	   # requires DBIx::SQLEngine::Cache::TrivialCache
	   $class_name->use_cache_style('simple');

       o

	   # requires Cache::FastMemoryCache from CPAN
	   $class_name->use_cache_style('active');

FETCHING DATA (SQL DQL)
       Each of these methods provides a	cached version of the superclass
       method.	The results of queries are cached based	on the SQL statement
       and parameters used.

       fetch_select()
	     $class_name->fetch_select(	%select_clauses	) : $record_set

	   Retrives records from the table using the provided SQL select
	   clauses.

       fetch_one_record()
	     $sqldb->fetch_one_record( %select_clauses ) : $record_hash

	   Retrives one	record from the	table using the	provided SQL select
	   clauses.

       select_record()
	     $class_name->select_record	( $primary_key_value ) : $record_obj
	     $class_name->select_record	( \@compound_primary_key ) : $record_obj
	     $class_name->select_record	( \%hash_with_primary_key_value	) : $record_obj

	   Fetches a single record by primary key.

       select_records()
	     $class_name->select_records ( @primary_key_values_or_hashrefs ) : $record_set

	   Fetches a set of one	or more	records	by primary key.

       visit_select()
	     $class_name->visit_select ( $sub_ref, %select_clauses ) : @results
	     $class_name->visit_select ( %select_clauses, $sub_ref ) : @results

	   Calls the provided subroutine on each matching record as it is
	   retrieved. Returns the accumulated results of each subroutine call
	   (in list context).

	   To Do: This could perform caching of	the matched records, but
	   currently does not.

       The conversion of select	clauses	to a SQL statement is performed	by the
       sql_select method:

       sql_select()
	     $class_name->sql_select ( %sql_clauses ) :	$sql_stmt, @params

	   Uses	the table to call the sql_select method	on the current
	   SQLEngine driver.

   Vivifying Records From The Database
       These methods are called	internally by the various select methods and
       do not need to be called	directly.

       record_from_db_data()
	     $class_name->record_from_db_data( $hash_ref )

	   Calls SUPER method, then cache_records().

       record_set_from_db_data()
	     $class_name->record_set_from_db_data( $hash_array_ref )

	   Calls SUPER method, then cache_records().

       cache_records()
	     $class_name->cache_records( @records )

	   Adds	records	to the cache.

EDITING	DATA (SQL DML)
   Insert to Add Records
       After constructing a record with	one of the new_*() methods, you	may
       save any	changes	by calling insert_record.

       insert_record
	     $record_obj->insert_record() : $flag

	   Attempt to insert the record	into the database. Calls SUPER method,
	   so implemented using	MIXIN.

	   Clears the cache.

   Update to Change Records
       After retrieving	a record with one of the fetch methods,	you may	save
       any changes by calling update_record.

       update_record
	     $record_obj->update_record() : $record_count

	   Attempts to update the record using its primary key as a unique
	   identifier.	Calls SUPER method, so implemented using MIXIN.

	   Clears the cache.

   Delete to Remove Records
       delete_record()
	     $record_obj->delete_record() : $record_count

	   Delete this existing	record based on	its primary key.  Calls	SUPER
	   method, so implemented using	MIXIN.

	   Clears the cache.

SEE ALSO
       For more	about the Record classes, see DBIx::SQLEngine::Record::Class.

       See DBIx::SQLEngine for the overall interface and developer
       documentation.

       See DBIx::SQLEngine::Docs::ReadMe for general information about this
       distribution, including installation and	license	information.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 95:
	   You can't have =items (as at	line 99) unless	the first thing	after
	   the =over is	an =item

perl v5.32.0			  2004-11-21	   SQLEngine::Record::Cache(3)

NAME | SYNOPSIS | DESCRIPTION | CACHE INTERFACE | FETCHING DATA (SQL DQL) | EDITING DATA (SQL DML) | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBIx::SQLEngine::Record::Cache&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help