HpcLinqQueryable.Apply Method (IQueryable, IQueryable, Expression)

Article
04/22/2013

Applies the specified function in a pairwise manner to the records from two specified sets of records.

Namespace: Microsoft.Hpc.Linq
Assembly: Microsoft.Hpc.Linq (in Microsoft.Hpc.Linq.dll)

Usage

'Usage
Dim source1 As IQueryable(Of T1)
Dim source2 As IQueryable(Of T2)
Dim applyFunc As Expression(Of Func(Of IEnumerable(Of T1), IEnumerable(Of T2), IEnumerable(Of T3)))
Dim returnValue As IQueryable(Of T3)

returnValue = HpcLinqQueryable.Apply(source1, source2, applyFunc)

Syntax

'Declaration
<ExtensionAttribute> _
Public Shared Function Apply(Of T1, T2, T3) ( _
    source1 As IQueryable(Of T1), _
    source2 As IQueryable(Of T2), _
    applyFunc As Expression(Of Func(Of IEnumerable(Of T1), IEnumerable(Of T2), IEnumerable(Of T3))) _
) As IQueryable(Of T3)

[ExtensionAttribute] 
public static IQueryable<T3> Apply<T1,T2,T3> (
    IQueryable<T1> source1,
    IQueryable<T2> source2,
    Expression<Func<IEnumerable<T1>,IEnumerable<T2>,IEnumerable<T3>>> applyFunc
)

[ExtensionAttribute] 
public:
generic<typename T1, typename T2, typename T3>
static IQueryable<T3>^ Apply (
    IQueryable<T1>^ source1, 
    IQueryable<T2>^ source2, 
    Expression<Func<IEnumerable<T1>^, IEnumerable<T2>^, IEnumerable<T3>^>^>^ applyFunc
)

J# supports the use of generic APIs, but not the declaration of new ones.

JScript does not support generic types or methods.

GenericParameters

T1
The type of the records in the source1 parameter.

T2
The type of the records in the source2 parameter.

T3
The return type of the function that you specify in the applyFunc parameter.

Parameters

source1
An System.Linq.IQueryable<T1> interface for the first set of records that you want to process.

source2
An System.Linq.IQueryable<T2> interface for the second set of records that you want to process.

applyFunc
An System.Linq.Expressions.Expression(Func(IEnumerable<T1>, IEnumerable<T2>, IEnumerable<T3>)) object that specifies the function that you want to apply to the records from the two sets of input. The first parameter contains records from the first set of records, and the second parameter contains records from the second set of records.

Return Value

An IQueryable interface that represents the set of records that results from applying the specified function to the two input set of records.

Exceptions

Exception type	Condition
ArgumentNullException	The specified source1 or source2 parameter is a null reference (Nothing in Visual Basic).

Remarks

To apply the function to records from a single set of records, use the Apply(Generic IQueryable,Generic Expression,Generic IEnumerable) form of the function. To apply the function to an arbitrary number of record sets, use the Apply(Generic IQueryable,Generic IQueryable,Generic Expression,Generic IEnumerable) form of the function.

If the function that you specify in the applyFunc parameter is marked with the LeftDistributiveOverConcat attribute, the function is distributive in its first parameter. but not in its second parameter. In other words, the data for the first parameter is only from the current DSC file, but the data for the second parameter is the data from all of the DSC files combined in a single enumerable object. The function runs in a distributed manner, once for each DSC file in the first set of input.

If the function that you specify in the applyFunc parameter is marked with the DistributiveOverConcat attribute, the function performs pairwise processing of the DSC files from the two sets of input. DSC files from both the source1 and source2 parameters are used. The first DSC file from source1 is paired with the first DSC file from source2, the second DSC file from source1 is paired with the first DSC file from source2, and so on. An exception occurs if the two sources of input do not have the same number of DSC files, although the sources are not required to have the same number of records.

If the function that you specify in the applyFunc parameter is marked with neither the LeftDistributiveOverConcat nor the DistributiveOverConcat attribute, the function runs on a single node. For each of the input sets of records, LINQ to HPC collects the records in a single enumerable object if records in the set are distributed across multiple compute nodes in the HPC cluster. LINQ to HPC then applies to the function to the records in the two resulting enumerable objects on a single compute node. The output of the function is a single enumerable object that becomes the result of the Apply operation.

The enumerable objects that are passed to the function that the applyFunc parameter specifies are designed to be streamed. Therefore, you can call the GetEnumerator method on each of those objects only once, and cannot call the Reset method to change the position of the enumerators.

In Visual Basic and C#, you can call this method as an instance method on any object of type IQueryable<TSource>. When you use instance method syntax to call this method, omit the first parameter. For more information, see Extension Methods (Visual Basic) or Extension Methods (C# Programming Guide).

This method has at least one parameter of type Expression with a type argument that is one of the Func types. For these parameters, you can pass in a lambda expression and it compiles to an Expression. For the Apply(Generic IQueryable,Generic IQueryable,Generic Expression,Generic IEnumerable,Generic IEnumerable) method, you should only use lambda expression in the form of x => function_name(x) or x => x.function_name(). When you specify a lambda expression with these forms, LINQ to HPC checks the attributes of function_name to determine if it is marked with the LeftDistributiveOverConcat or DistributiveOverConcat attribute. If you use a lambda expression of another form, such as one that includes compound expressions, LINQ to HPC ignores these attributes for any methods that occur in subexpressions, which could result in unintended behavior.

For more information about this method, see "Binary Apply" in the LINQ to HPC and DSC Programmer's Guide.

Platform Note: This method was introduced in Windows HPC Server 2008 R2 with Service Pack 2 (SP2) and is not supported in previous versions.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

Windows XP, Windows Vista, Windows 7, Windows 8, Windows Server 2003, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012

Target Platforms

Windows XP, Windows Vista, Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2008, Windows Server 2008 R2, with HPC Pack Client Utilities