Roxen.git/ server/ base_server/ roxen.pike

Branch: Tag:

2000-07-27

2000-07-27 00:48:21 by Johan Sundström <oyasumi@gmail.com>

Refdoc now covers most aspects of the argcache and imagecache. Still
left to cover, however, is the draw callback beast, along with its
parameters and returnvalue. Oh, and the image loader methods too.

Rev: server/base_server/roxen.pike:1.513

4:   // Per Hedbor, Henrik Grubbström, Pontus Hagland, David Hedbor and others.      // ABS and suicide systems contributed freely by Francesco Chemolli - constant cvs_version="$Id: roxen.pike,v 1.512 2000/07/25 16:19:43 marcus Exp $"; + constant cvs_version="$Id: roxen.pike,v 1.513 2000/07/27 00:48:21 jhs Exp $";      // Used when running threaded to find out which thread is the backend thread,   // for debug purposes only.
2059:         class ImageCache + //! The image cache handles the behind-the-scenes caching and + //! regeneration features of graphics generated on the fly. Besides + //! being a cache, however, it serves a wide variety of other + //! interesting image conversion/manipulation functions as well.   {    string name;    string dir;
2417:    }       void flush(int|void age) +  //! Flush the cache. If an age (an integer as returned by +  //! <pi>time()</pi>) is provided, only images generated earlier than +  //! that are flushed.    {    report_debug("Flushing "+name+" image cache.\n");    foreach(r_get_dir(dir), string f)
2425:    r_rm(dir+f);    }    -  array status(int|void age) { +  array(int) status(int|void age) +  //! Return the total number of images in the cache, their cumulative +  //! sizes in bytes and, if an age time_t was supplied, the number of +  //! images generated earlier than that (see <ref>flush()</ref>). +  //! (These three integers are returned regardless of whether an age +  //! parameter was given.) +  {    int files=0, size=0, aged=0;    array stat;    foreach(r_get_dir(dir), string f)
2460:    }       -  string data( string|mapping args, RequestID id, int|void nodraw ) +  string data( array|string|mapping args, RequestID id, int|void nodraw ) +  //! Returns the actual raw image data of the image rendered from the +  //! `data' instructions. +  //! +  //! A non-zero `nodraw' parameter means an image not already in the +  //! cache will not be rendered on the fly, but instead return zero.    {    string na = store( args, id );    mixed res;
2477:    return res->data;    }    -  mapping http_file_answer( string|mapping data, +  mapping http_file_answer( array|string|mapping data,    RequestID id,    int|void nodraw ) -  +  //! Returns a <ref>result mapping</ref> like one generated by +  //! <ref>Roxen.http_file_answer()</ref> but for the image file +  //! rendered from the `data' instructions. +  //! +  //! Like <ref>metadata</ref>, a non-zero `nodraw' parameter means an +  //! image not already in the cache will not be rendered on the fly, +  //! but instead return zero (for request not handled).    {    string na = store( data,id );    mixed res;
2493:    return res;    }    -  mapping metadata( string|mapping data, RequestID id, int|void nodraw ) +  mapping metadata( array|string|mapping data, +  RequestID id, +  int|void nodraw ) +  //! Returns a mapping of image metadata for an image generated from +  //! the data given (as sent to <ref>store()</ref>). If a non-zero +  //! `nodraw' parameter is given and the image was not in the cache, +  //! it will not be rendered on the fly to get the correct data.    {    string na = store( data,id );    if(!restore_meta( na ))
2514:    }       string store( array|string|mapping data, RequestID id ) +  //! Store the data your draw callback expects to receive as its +  //! first argument(s). If the data is an array, the draw callback +  //! will be called like <pi>callback( @data, id )</pi>.    {    string ci;    if( mappingp( data ) )    ci = argcache->store( data );    else if( arrayp( data ) ) -  ci = Array.map( Array.map( data, tomapp ), argcache->store )*"$"; +  ci = map( map( data, tomapp ), argcache->store )*"$";    else    ci = data;    return ci;    }       void set_draw_function( function to ) -  +  //! Set a new draw function.    {    draw_function = to;    }       void create( string id, function draw_func, string|void d ) -  +  //! Instantiate an image cache of your own, whose image files will +  //! be stored in a directory `id' in the argument cache directory, +  //! typically <tt>../var/cache/</tt>. If you supply the optional +  //! third parameter, this path will be used instead of the common +  //! argument cache directory. +  //! +  //! The `draw_func' callback passed will be responsible for +  //! (re)generation of the images in the cache. Your draw callback +  //! may take any arguments you want, depending on the first argument +  //! you give the <ref>store()</ref> method, but its final argument +  //! will be the RequestID object.    {    if(!d) d = roxenp()->query("argument_cache_dir");    if( d[-1] != '/' )
2547:         class ArgCache + //! Generic cache for storing away a persistent mapping of data to be + //! refetched later by a short string key. This being a cache, your + //! data may be thrown away at random when the cache is full.   {    static string name;    static string path;
2581:    void create( string _name,    string _path,    int _is_db ) +  //! Instantiates an argument cache of your own. +  //! +  //! A value of 0 for the <tt>is_db</tt> parameter will make your +  //! argument cache store its data in the regular filesystem, in a +  //! directory <tt>name</tt> created at <tt>path</tt>. +  //! +  //! A value of 1 for the <tt>is_db</tt> parameter will make your +  //! argument cache store its data in a database, <tt>path</tt> being +  //! an <ref>SQL url</ref>, <tt>name</tt> being the name of the table +  //! in that database.    {    name = _name;    path = _path;
2673:          int key_exists( string key ) +  //! Does the key 'key' exist in the cache? Returns 1 if it does, 0 +  //! if it was not present.    {    LOCK();    if( !is_db )
2681:    }       string store( mapping args ) +  //! Store a mapping (of purely encode_value:able data) in the +  //! argument cache. The string returned is your key to retrieve the +  //! data later.    {    LOCK();    array b = values(args), a = sort(indices(args),b);
2714:    }       mapping lookup( string id, array|void client ) +  //! Recall a mapping stored in the cache. The optional client array +  //! may be supplied to get an error message stating the browser name +  //! in the event of the key not being present any more in the cache.    {    LOCK();    if(cache[id] && cache[ cache[id] ] )
2737:    }       void delete( string id ) +  //! Remove the data element stored under the key 'id'.    {    LOCK();    if(cache[id])
2851:   // report_debug( "[Configuration: %.2fms] ", (gethrtime()-s)/1000.0);   }    - // Set the uid and gid to the ones requested by the user. If the sete* - // functions are available, and the define SET_EFFECTIVE is enabled, - // the euid and egid is set. This might be a minor security hole, but - // it will enable roxen to start CGI scripts with the correct - // permissions (the ones the owner of that script have). -  +    int set_u_and_gid() -  + //! Set the uid and gid to the ones requested by the user. If the + //! sete* functions are available, and the define SET_EFFECTIVE is + //! enabled, the euid and egid is set. This might be a minor security + //! hole, but it will enable roxen to start CGI scripts with the + //! correct permissions (the ones the owner of that script have).   {   #ifndef __NT__    string u, g;