[SparForte][Banner]
[Top Main Menu] Intro | Tutorials | Reference | Packages | Examples | Contributors   [Back Page]      [Next Page]  

Memcache.Highread Package

A package for storing data in memcached with optional redundancy, optimized for more reads than writes.

GCC Ada Equivalent: N/A
See Also: memcache

Memcached (or the Memcache Daemon) is a general-purpose networked memory caching system that was originally developed by Danga Interactive for LiveJournal, but is now used by many other sites. It is often used to speed up dynamic database-driven websites by caching data and objects in RAM to reduce the number of times an external data source (such as a database or API) must be read. Memcached has been used by web sites including YouTube, Facebook and Twitter.

Values are store as keys (names or labels) and the associated value.

SparForte supports memcached natively (that is, using pragmas you can import and export variable to/from Memcached.) The memcached support is built on the PegaSoft PegaSock socket library, which supports local memcached caching as well as distributed, redundant memcached caching clusters.

The Memcache.highread package is a binding to the PegaSock library, giving a more flexible interface to memcache than the pragmas provide. For example, you can use any keys you want, rather than using the variable name as the key. The names of the procedures and functions are equivalent to the commands of the memcached protocol: you can find out more information on them by consulting the memcached documentation.

The following is a trivial example with one memcached server running on localhost port 11211.

=> c := memcache.highread.new_cluster
=> (Assuming c is a new memcache.memcache_dual_cluster variable)
=> memcache.highread.register_alpha_server( c, "localhost", 11211 )
=> memcache.highread.register_beta_server( c, "localhost", 11212 )
=> key : string := "candy"
=> memcache.highread.set( c, key, "cane" )
=> ? memcache.highread.get( c, key )
cane
=>
 

Example: Setting key "candy" to value "cane" and retrieving it again

Normally a memcache cluster would have two or more servers. The key would automatically be stored on two servers. If a server in the cluster fails, a program can still retrieve the data.

The highread package uses two normal memcache clusters, using them as if they were a single cluster. Data is stored up to four times in servers, and the get function can read from any of the four servers. This makes it a good choice for high redundancy tasks, or takes where there are more reads than writes.

PegaSock implements an escallating backoff mechanism: if a server cannot be accessed, it is marked as down. After a suitable period, PegaSock will attempt to reconnect. If both servers containing the data are down, the next few memcache calls automatically fail. If the servers are still down, it backs off for a longer period of time. This is done to prevent a cascading failure.

Some functionality (such as cas) is not implemented.

Because memcached has no security features, running in a restricted shell will disable the memcache.highread package. It can also be disabled with pragma restriction.

memcache.highread.add( cl, k, v )

 

Store value v for key k in memcache cluster cl if the key does not exist. Otherwise, an error is displayed but execution continues.

Example

memcache.highread.add( mc_cluster, "company_name", "PegaSoft" );

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
k in any string type required the name to identify the value
v in any string type required the value to store

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.set
memcache.highread.replace

Compare With

Ada: PegaSock.Memcache.Highread.Add

memcache.highread.append( cl, k, v )

 

Concatenate value v to the end of the current value for key k in memcache cluster cl.

Example

memcache.highread.set( mc_cluster, "company_name", "PegaSoft" );
memcache.highread.append( mc_cluster, "company_name", " Inc.";
-- company_name is "PegaSoft Inc."

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
k in any string type required the name to identify the value
v in any string type required the value to append

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.prepend

Compare With

Ada: PegaSock.Memcache.Append

memcache.highread.clear_servers( cl )

 

Delete all registered servers for memcache cluster cl. The data is not flushed from memcached.

Example

memcache.highread.clear_servers( cl ); -- there are now no servers in the cluster

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use

Exceptions

-

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.register_alpha_server
memcache.highread.register_beta_server

Compare With

Ada: Pegasock.Memcache.Highread.Clear_Servers

memcache.highread.delete( cl, k )

 

Remove key k from memcache cluster cl, discarding the key's value.

Example

memcache.highread.delete( mc_cluster, "company_name", "PegaSoft" );
-- company_name no longer exists

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
k in any string type required the key name to unset

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.flush

Compare With

Ada: PegaSock.Memcache.Highread.Delete

memcache.highread.flush( cl )

 

Delete all keys. The memory is not actually freed: all keys are marked invalid and are gradually replaced as new items are stored.

Example

memcache.highread.flush( mc_cluster );-- all keys are destroyed

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.delete

Compare With

Ada: PegaSock.Memcache.Highread.Flush

v := memcache.highread.get( cl, k )

 

Look up the value previously stored for the key k in memcache cluster cl and return it. If the key does not exist, return an empty string. If there are two or more servers in the cluster, get will alternate between the servers with the key in order to distribute load.

Example

memcache.highread.set( mc_cluster, "company_name", "PegaSoft" );
? memcache.highread.get( mc_cluster, "company_name" );
-- displays "PegaSoft"

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
k in any string type required the name to identify the value
v return value any string type required the value

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

See Also

-

Compare With

Ada: PegaSock.Memcache.Highread.Get

cl := memcache.highread.new_cluster

 

Allocate a new memcache cluster record. The record is used to identify servers and manage connections.

Example

mc_cluster := memcache.highread.new_cluster;

Parameters

Param Mode Type Default Description
cl return value memcache.memcache_dual_cluster required the new memcache cluster

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

Implementation Notes

Because the memcache_cluster record is private, SparForte allocates clusters internally using a linked list. The records are not freed until the script execution end.

See Also

-

Compare With

Ada: N/A

memcache.highread.prepend( cl, k, v )

 

Concatenate value v to the head of the current value for key k in memcache cluster cl.

Example

memcache.highread.set( mc_cluster, "company_name", "PegaSoft" );
memcache.highread.prepend( mc_cluster, "company_name", "This is " );
-- company_name is "This is PegaSoft"

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
k in any string type required the name to identify the value
v in any string type required the value to prepend

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.append

Compare With

Ada: PegaSock.Memcache.Highspeed.Prepend

memcache.highread.register_alpha_server( cl, h, p )

 

Identify a new server to use in the memcache cluster. The server is identified by hostname h and TCP/IP port p. The servers should always be registered in the same order for this cluster. No network connection is opened: network connections are opened when data is read or written. Do not register the same server twice.

Example

memcache.highread.register_alpha_server( mc_cluster, "memcached1.somecompany.com", 11211 );

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
h in any string type required the host name
p in natural required the TCP/IP port

Exceptions

An exception is raised if a server is registered twice.

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.clear_servers

Compare With

Ada: PegaSock.Memcache.Highread.RegisterBetaServer

memcache.highread.register_beta_server( cl, h, p )

 

Identify a new server to use in the memcache cluster. The server is identified by hostname h and TCP/IP port p. The servers should always be registered in the same order for this cluster. No network connection is opened: network connections are opened when data is read or written. Do not register the same server twice.

Example

memcache.highread.register_beta_server( mc_cluster, "memcached2.somecompany.com", 11211 );

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
h in any string type required the host name
p in natural required the TCP/IP port

Exceptions

An exception is raised if a server is registered twice.

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.clear_servers

Compare With

Ada: PegaSock.Memcache.Highread.RegisterAlphaServer

memcache.highread.replace( cl, k, v )

 

Overwrite the current value of key k memcache cluster cl with value v, if a value already exists. If the key doesn't exist, a warning is displayed but execution continues.

Example

memcache.highread.set( mc_cluster, "company_name", "PegaSoft" );
memcache.highread.replace( mc_cluster, "company_name", "MegaCorp";
-- company_name is "MegaCorp"

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
k in any string type required the name to identify the value
v in any string type required the value to overwrite with

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.add
memcache.highread.set

Compare With

Ada: PegaSock.Memcache.Highread.Replace

memcache.highread.set( cl, k, v )

 

Assign value v as the current value for key k in memcache cluster cl. If the key already has a value, it will be overwritten.

Example

memcache.highread.set( mc_cluster, "company_name", "PegaSoft" );
-- company_name is "PegaSoft"

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
k in any string type required the name to identify the value
v in any string type required the value to assign

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.add
memcache.highread.replace

Compare With

Ada: PegaSock.Memcache.Highread.Set

memcache.highread.set_cluster_name( cl, s )

 

Assign the string s as the name of the cluster. The name is used in some error messages.

Example

memcache.highread.set_cluster_name( mc_cluster, "main cluster" );

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
s in any string type required the name of the cluster

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

-

Compare With

Ada: PegaSock.Memcache.Highread.SetClusterName

memcache.highread.set_cluster_type( cl, t )

 

Assign the type of cluster. Currently, there is only one type: memcache.memcache_cluster_type.normal.

Example

memcache.highread.set_cluster_type( mc_cluster, memcache.memcache_cluster_type.normal );

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
s in memcache.highread.memcache_cluster_type required the type of cluster

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

-

Compare With

Ada: PegaSock.Memcache.Highread.SetClusterType

s := memcache.highread.stats( cl )

 

Return detailed memached statistics for all servers in the cluster. The first item in the row is either "alpha" or "beta" followed by the server number. For the meaning of the stats, consult the memcached documentation.

Example

? memcache.highread.stats( mc_cluster );-- display all stats

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
s return value string required the memcached stats

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.version

Compare With

Ada: PegaSock.Memcache.Highread.Stats

s := memcache.highread.version( cl )

 

Chooses a server from the cluster at random and display the version of memcached that is running on the server. (It would be advisable to run the same version on all servers.)

Example

? memcache.highread.version( mc_cluster ); -- displays the version e.g. 1.4.5

Parameters

Param Mode Type Default Description
cl in out memcache.memcache_dual_cluster required the memcache cluster to use
s return value string required the memcached version

Exceptions

An exception is thrown if no servers are defined in either cluster within the dual cluster

Restrictions

Not allowed in a restricted shell or with the no_memcache restriction

See Also

memcache.highread.stats

Compare With

Ada: PegaSock.Memcache.Highread.Version

 
[Right Submenu]

 Summary

 arrays

 btree_io

 calendar

 cgi

 chains

 command_line

 db/ postgresql

 dbm

 directory_operations

 doubly_linked...

 dynamic_hash_...

 enums

 exceptions

 files

 gnat.cgi

 gnat.crc32

 hash_io

 lock_files

 memcache

 memcache.highread

 mysql

 mysqlm

 numerics

 os

 pen

 pen (OpenGL)

 records

 sound

 source_info

 stats

 strings

 System

 teams

 templates

 text_io

 units

[Back to Top] Back To Top [Small Forte Symbol]