On Sun, 13 May 2007 22:46:15 -0700 Mike Mattie <[EMAIL PROTECTED]> wrote:
> Hello,
>
[snip RFC]
Here is a revised and cleaned up specification of the search algorithm taken
from my current description
of the Parrot_locate_runtime_str function.
/*
=item C<char* Parrot_locate_runtime_file(Interp *,
const char *object_name,
STRING *hll
enum_runtime_ft *loader
STRING* trace)>
Parrot_locate_runtime_str searches the filesystem for object files
containing code of some sort. This functionality is shared by several
opcodes/components and is designed with parrot's unusual flexiblity in
mind.
object_name : the name of the object to load. It can be simply a name,
path, or absolute path.
hll : The hll argument is the key to the HLL name-space. The
default namespace is used if the namespace does not exist
or is null.
The default name-space is "parrot".
loader : a bit-mask selecting loaders to be included in the search.
This arguement is passed by reference. When a matching file
is found the value of loader is reset to the flag for the
loader under which it was found.
loader is not modified unless a matching file is found.
trace : given non-null string a trace of the search will be appended.
This allows higher level API's to capture detailed diagnostics
when the search fails. This is useful for all parties.
The return value is:
* a string containing the path to the objects preferred form, or NULL if not
found.
* localized with parrot_platform_path_localize
* all path seperators are coverted to the platform's value (ie Win32)
* a hidden 0 char is appended making it suitable for direct use in C API
calls,
an artifact of the previous implementation.
Search behavior:
code objects can have several formats, some of which will be stored on
disk. This routine searches for the preferred format of an object.
Preferred is either lowest form (compiled), or highest form (source).
The given search rules apply at each step in the search order. The
search order is executed per loader. The loader mask is also traversed
in preferred the order.
rule 1: parrot will always try the object_name as given before adding
extensions. The set of extensions tried is loader specific.
Search order:
1. Absolute paths (return or fail)
2. Search the paths joined with get_runtime_prefix
3. joined with get_runtime_prefix
4. as given
Exception 1. absolute paths in the path list are not prefixed
Exception 2. If the loader mask is zero: step two of the search order
will be skipped. extensions are skipped since there
is no loader information available.
The two modals for the search are the runtime_prefix and preferred
order.
SEE ALSO: Parrot_get_runtime_prefix, query_load_prefer ,
F<include/parrot/library.h>
current parrot behavior can be achieved by passing NULL as the hll
argument, and a loader mask of:
PARROT_RUNTIME_FT_BYTECODE &
PARROT_RUNTIME_FT_INCLUDE &
PARROT_RUNTIME_FT_SOURCE
for parrot bytecode, and PARROT_RUNTIME_FT_ARCH for platform shared
objects.
Implementation Notes:
The implementation of the search behavior is tagged in this file.
rules : grep search-rule x
search order : grep search-order x
search exception : grep search-rule x
The search lists for both paths and extensions are dynamic arrays. In
the extension search space it is assumed that the lowest index
corresponds to the lowest form, and that the array is sorted
accordingly.
TODO: the extension , which is actually the stage of interpretation contained
by the format is returned in the extension of the file. This should be
returned as a optimization hint to heuristics that do the real
determination of what's in a file , ( example: use v6; or shebang
invocations )
TODO: instead of a string that is checked by stat() , a handle should be
returned instead to close the classic access() race. Additional
flags are needed for that such as NO_TTY and other basic cross-platform
security open() masks. <-- huge warning.
(This should be relative to a loader , higher level forms may
have looser security constraints)
TODO: OS IO/VM hinting. some loaders could benefit from IO hinting such as
mapped/streamed, use-once etc. depends on returning a handle and open
flags.
=cut
*/
>
> Cheers,
> Mike Mattie - [EMAIL PROTECTED]
>
>
>
>
signature.asc
Description: PGP signature
