NAME

src/multidispatch.c - Multimethod dispatch for binary opcode functions

SYNOPSIS

This system is set up to handle type-based dispatching for binary (two argument) functions. This includes, though isn't necessarily limited to, binary operators such as addition or subtraction.

DESCRIPTION

The MMD system is straightforward, and currently must be explicitly invoked, for example by a vtable function. (We reserve the right to use MMD in all circumstances, but currently do not).

API

For the purposes of the API, each MMD-able function is assigned a unique number which is used to find the correct function table. This is the func_num parameter in the following functions. While Parrot isn't restricted to a predefined set of functions, it does set things up so that all the binary vtable functions have a MMD table preinstalled for them, with default behaviour.

Remarks

binop_mmd_funcs->x and ->y are table sizes not highest type in table.

Functions

PMC *Parrot_mmd_find_multi_from_sig_obj

Collect a list of possible candidates for a given sub name and call signature. Rank the possible candidates by Manhattan Distance, and return the best matching candidate. The candidate list is cached in the CallSignature object, to allow for iterating through it.Currently this only looks in the global "MULTI" namespace.

void Parrot_mmd_multi_dispatch_from_c_args

Dispatches to a MultiSub from a variable-sized list of C arguments. The multiple dispatch system will figure out which sub should be called based on the types of the arguments passed in.Return arguments must be passed as a reference to the PMC, string, number, or integer, so the result can be set.

PMC *Parrot_mmd_find_multi_from_long_sig

Find the best candidate multi for a given sub name and signature. The signature is a string containing a comma-delimited list of type names.Currently only searches the global MULTI namespace.

PMC *Parrot_mmd_sort_manhattan_by_sig_pmc

Given an array PMC (usually a MultiSub) and a CallSignature PMC, sorts the mmd candidates by their manhattan distance to the signature args and returns the best one.

PMC *Parrot_mmd_sort_manhattan

Given an array PMC (usually a MultiSub) sorts the mmd candidates by their manhattan distance to the current args and returns the best one.

static PMC *Parrot_mmd_arg_tuple_func

Return a list of argument types. PMC arguments are taken from registers according to calling conventions.

static void Parrot_mmd_search_classes

Search all the classes in all MultiSubs of the candidates cl and return a list of all candidates. start_at_parent is 0 to start at the class itself or 1 to search from the first parent class.

static INTVAL distance_cmp

RT #48260: Not yet documented!!!

static PMC *mmd_build_type_tuple_from_type_list

Construct a FixedIntegerArray of type numbers from an array of type names. Used for multiple dispatch.

static PMC *mmd_build_type_tuple_from_long_sig

Construct a FixedIntegerArray of type numbers from a comma-delimited string of type names. Used for multiple dispatch.

PMC *Parrot_mmd_build_type_tuple_from_sig_obj

Construct a FixedIntegerArray of type numbers from the arguments of a Call Signature object. Used for multiple dispatch.

static PMC *mmd_cvt_to_types

Given a ResizablePMCArray PMC containing some form of type identifier (either the string name of a class or a PMC representing the type), resolves all type references to type IDs, if possible. If that's not possible, returns PMCNULL. In that case you can't dispatch to the multi variant with this type signature, as Parrot doesn't yet know about the respective types requested -- you have to register them first.Otherwise, returns a ResizableIntegerArray PMC full of type IDs representing the signature of a multi variant to which you may be able to dispatch.{{**DEPRECATE**}}

static UINTVAL mmd_distance

Create Manhattan Distance of sub pmc against given argument types. 0xffff is the maximum distance

static PMC *Parrot_mmd_sort_candidates

Sort the candidate list cl by Manhattan Distance, returning the best candidate.

static PMC *Parrot_mmd_search_scopes

Search all scopes for MMD candidates matching the arguments given in arg_tuple.

static int mmd_maybe_candidate

If the candidate pmc is a Sub PMC, push it on the candidate list and return TRUE to stop further search.If the candidate is a MultiSub remember all matching Subs and return FALSE to continue searching outer scopes.

static int mmd_search_local

Search the current package namespace for matching candidates. Return TRUE if the MMD search should stop.

static void mmd_search_by_sig_obj

Search the namespace of the first argument to the sub call for matching candidates.

static void mmd_search_global

Search the builtin namespace for matching candidates.

static void mmd_add_multi_global

Create a MultiSub, or add a variant to an existing MultiSub. The MultiSub is stored in the global MULTI namespace.

static void mmd_add_multi_to_namespace

Create a MultiSub, or add a variant to an existing MultiSub. The MultiSub is added as a method to a class.

void Parrot_mmd_add_multi_from_long_sig

Create a MultiSub, or add a variant to an existing MultiSub. The MultiSub is stored in the global MULTI namespace.

void Parrot_mmd_add_multi_from_c_args

Create a MultiSub, or add a variant to an existing MultiSub. The MultiSub is stored in the specified namespace.

void Parrot_mmd_add_multi_list_from_c_args

Create a collection of multiple dispatch subs from a C structure of information. Iterate through the list of details passed in. For each entry create a MultiSub or add a variant to an existing MultiSub. MultiSubs are created in the global 'MULTI' namespace in the Parrot HLL.Typically used to create all the multiple dispatch routines declared in a PMC from the PMC's class initialization function.

MMD_Cache *Parrot_mmd_cache_create

Creates and returns a new MMD cache.

static STRING *mmd_cache_key_from_values

Generates an MMD cache key from an array of values.

PMC *Parrot_mmd_cache_lookup_by_values

Takes an array of values for the call and does a lookup in the MMD cache.

void Parrot_mmd_cache_store_by_values

Takes an array of values for the call along with a chosen candidate and puts it into the cache.

static STRING *mmd_cache_key_from_types

Generates an MMD cache key from an array of types.

PMC *Parrot_mmd_cache_lookup_by_types

Takes an array of types for the call and does a lookup in the MMD cache.

void Parrot_mmd_cache_store_by_types

Takes an array of types for the call along with a chosen candidate and puts it into the cache. The name parameter is optional, and if the cache is already tied to an individual multi can be null.

void Parrot_mmd_cache_mark

GC-marks an MMD cache.

void Parrot_mmd_cache_destroy

Destroys an MMD cache.

SEE ALSO

include/parrot/multidispatch.h, http://svn.perl.org/perl6/doc/trunk/design/apo/A12.pod, http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod