MOOCHO (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Functions
Reduction/Transformation Operator Interface Functions (virtual).
Collaboration diagram for Reduction/Transformation Operator Interface Functions (virtual).:

Functions

int RTOp_get_op_name (const struct RTOp_RTOp *op, const char **op_name)
 
int RTOp_get_op_type_num_entries (const struct RTOp_RTOp *op, int *num_values, int *num_indexes, int *num_chars)
 
int RTOp_extract_op_state (const struct RTOp_RTOp *op, int num_values, RTOp_value_type value_data[], int num_indexes, RTOp_index_type index_data[], int num_chars, RTOp_char_type char_data[])
 
int RTOp_load_op_state (int num_values, const RTOp_value_type value_data[], int num_indexes, const RTOp_index_type index_data[], int num_chars, const RTOp_char_type char_data[], struct RTOp_RTOp *op)
 
int RTOp_free_op (struct RTOp_RTOp *op)
 
int RTOp_get_reduct_type_num_entries (const struct RTOp_RTOp *op, int *num_values, int *num_indexes, int *num_chars)
 
int RTOp_reduct_obj_create (const struct RTOp_RTOp *op, RTOp_ReductTarget *reduct_obj)
 
int RTOp_reduct_obj_reinit (const struct RTOp_RTOp *op, RTOp_ReductTarget reduct_obj)
 
int RTOp_reduct_obj_free (const struct RTOp_RTOp *op, RTOp_ReductTarget *reduct_obj)
 
int RTOp_extract_reduct_obj_state (const struct RTOp_RTOp *op, const RTOp_ReductTarget reduct_obj, int num_values, RTOp_value_type value_data[], int num_indexes, RTOp_index_type index_data[], int num_chars, RTOp_char_type char_data[])
 
int RTOp_load_reduct_obj_state (const struct RTOp_RTOp *op, int num_values, const RTOp_value_type value_data[], int num_indexes, const RTOp_index_type index_data[], int num_chars, const RTOp_char_type char_data[], RTOp_ReductTarget reduct_obj)
 
int RTOp_coord_invariant (const struct RTOp_RTOp *op, int *coord_invariant)
 
int RTOp_apply_op (const struct RTOp_RTOp *op, const int num_vecs, const struct RTOp_SubVector sub_vecs[], const int num_targ_vecs, const struct RTOp_MutableSubVector targ_sub_vecs[], RTOp_ReductTarget reduct_obj)
 
int RTOp_reduce_reduct_objs (const struct RTOp_RTOp *op, RTOp_ReductTarget in_reduct_obj, RTOp_ReductTarget inout_reduct_obj)
 
int RTOp_get_reduct_op (const struct RTOp_RTOp *op, RTOp_reduct_op_func_ptr_t *reduct_op_func_ptr)
 

Detailed Description

Functions that act virtual with respect to reduction/transformation operators and are used by clients of abstract vectors and by vector implementations to apply these operators.

These functions are used as conveniences and call the virtual functions in the vtbl of the RTOp_RTOp object and pass in the obj_data pointer. Therefore, these nonmember functions act polymorphically with respect to the operator object. These functions could be implemented as macros to allow them to be inlined but we all know the problems with macros. The extra function call should not impose too much extra overhead. Because of the potential for macro inlining, the client should not (and should never need to) take the address of one of these functions.

The functions RTOp_get_op_type_num_entries<tt>(...) and RTOp_get_reduct_type_num_entries<tt>(...) are used for externalizing information about the structure of the instance data for reduction/transformation operator objects and for reduction objects. These functions are needed to externalize the representation of these objects so that these objects can be copied by the client and passed over networks between heterogeneous computers. This is needed to allow a client/server usage with reduction/transformation operators (see RTOp_Server).

To better understand the functions that deal with the opaque reduction target objects, the relationship between reduction/transformation operators and reduction target objects must be clarified. A reduction object is intimately associated with and is completely owned by an operator object. In any process, an reduction object can only come into existance by calling the method ::RTOp_reduct_obj_create<tt>(op,&reduct_obj). Once a reduct_obj is created, the memory footprint of the object is set. If the operator object is later modified in any way (i.e. by RTOp_load_op_state<tt>(op,...)) the the earlier created reduct_obj may no longer be compatible with its op object. The implementation of RTOp_load_reduct_obj_state<tt>(op,...,reduct_obj) is not allowed to change the memory footprint of reduct_obj. All of these restrictions are meant to allow for more simplicity in RTOp operator implementations.

Function Documentation

int RTOp_get_op_name ( const struct RTOp_RTOp op,
const char **  op_name 
)

Return the name (as a null-terminated C-style string) of the operator.

This name is used to differentate an operator subclass from all other operator subclasses. This is an important property needed for a client/server and other advanced computing configurations.

Parameters
op[in] The polymorphic reduction/transformation operator object
op_name[out] Null-terminated string for the name of the operator type
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 108 of file RTOp.c.

int RTOp_get_op_type_num_entries ( const struct RTOp_RTOp op,
int *  num_values,
int *  num_indexes,
int *  num_chars 
)

Get the number of members of each datatype in the object's externalized state data.

See RTOp_obj_type_vtbl_t for a description of this function.

Parameters
op[in] The polymorphic reduction/transformation operator object
num_values[out] Number of RTOp_value_type members
num_indexes[out] Number of RTOp_index_type members
num_chars[out] Number of RTOp_char_type members
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 123 of file RTOp.c.

int RTOp_extract_op_state ( const struct RTOp_RTOp op,
int  num_values,
RTOp_value_type  value_data[],
int  num_indexes,
RTOp_index_type  index_data[],
int  num_chars,
RTOp_char_type  char_data[] 
)

Externalize the state of the operator object to a portable format.

This function allows the state of an arbitrary reduction/transformation operator to be transported across a hetergeneous network and have it reconstructed in other processes (using RTOp_load_op_state<tt>(...)).

See RTOp_obj_type_vtbl_t for a description of this function.

Returns
Returns 0 if successful, !=0 otherwise.

Definition at line 144 of file RTOp.c.

int RTOp_load_op_state ( int  num_values,
const RTOp_value_type  value_data[],
int  num_indexes,
const RTOp_index_type  index_data[],
int  num_chars,
const RTOp_char_type  char_data[],
struct RTOp_RTOp op 
)

Load the state of the operator object from a portable format.

Note that this function can be called on an uninitilized operator object (i.e. op->obj_data == NULL) and in this case, the state data will be dynamicallly allocated in a way that is compatible with the constructors and destructors for the operator class (not given here obviously). The memory footprint for the operator object may change as a result of this operation even if it has already been initialized.

See RTOp_obj_type_vtbl_t for a description of this function.

Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 170 of file RTOp.c.

int RTOp_free_op ( struct RTOp_RTOp op)

Destroy the state data for this object.

Parameters
op[in/out] On input, if op->obj_data != NULL then this data will be freed in a way that is compatible with the classes concrete constructors (not given here of course) and with RTOp_load_op_state<tt>(...). On output, op->obj_data and op->vtbl will be set to NULL.
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 197 of file RTOp.c.

int RTOp_get_reduct_type_num_entries ( const struct RTOp_RTOp op,
int *  num_values,
int *  num_indexes,
int *  num_chars 
)

Get the number of members of each datatype in the reduction object.

See RTOp_obj_type_vtbl_t for a description of this function.

Parameters
op[in] The polymorphic reduction/transformation operator object.
num_values[out] Number of RTOp_value_type members in the object op.obj_data.
num_indexes[out] Number of RTOp_index_type members in the object op.obj_data.
num_chars[out] Number of RTOp_char_type members in the object op.obj_data.
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 209 of file RTOp.c.

int RTOp_reduct_obj_create ( const struct RTOp_RTOp op,
RTOp_ReductTarget reduct_obj 
)

Allocate and initialize the reduction object that will be used in the reduction operations.

If RTOp_get_reduct_type_num_entries<tt>(...) returns num_values == 0 , num_indexes == 0 and num_chars == 0 then this function should not be called and may be an error if attempted.

Parameters
op[in] The polymorphic reduction/transformation operator object
reduct_obj[out] On output *reduct_obj contains the pointer to the allocated target object. Also, *reduct_obj will be initialized ready for use in the reduction operations. If *reduct_obj contains the pointer to an already allocated object on input, it will not be freed (see RTOp_reduct_obj_free<tt>(...)).
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 230 of file RTOp.c.

int RTOp_reduct_obj_reinit ( const struct RTOp_RTOp op,
RTOp_ReductTarget  reduct_obj 
)

Reinitialize an already allocated target object.

If RTOp_get_reduct_type_num_entries<tt>(...) returns num_values == 0 , num_indexes == 0 and num_chars == 0 then this function should not be called and may be an error if attempted.

Parameters
op[in] The reduction/transformation operator object. This must be the same object that was used in the call to ::RTOp_reduct_obj_create<tt>(op,reduct_obj)
reduct_obj[out] On output reduct_obj will be reinitialized ready for use in reduction operations. This object must have been created by the ::RTOp_reduct_obj_create<tt>(op,reduct_obj) function first.
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 249 of file RTOp.c.

int RTOp_reduct_obj_free ( const struct RTOp_RTOp op,
RTOp_ReductTarget reduct_obj 
)

Free a target object that was previously allocated.

If RTOp_get_reduct_type_num_entries<tt>(...) returns num_values == 0 , num_indexes == 0 and num_chars == 0 then this function should not be called and may be an error if attempted.

Parameters
op[in] The reduction/transformation operator object. This must be the same object that was used in the call to ::RTOp_reduct_obj_create<tt>(op,reduct_obj)
reduct_obj[in/out] On input *reduct_obj is the pointer to an allocated target object. It is allowed that *reduct_obj == RTOp_REDUCT_OBJ_NULL on input and if so then nothing happens. This object is then freed and then on output *reduct_obj will be set to RTOp_REDUCT_OBJ_NULL
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 267 of file RTOp.c.

int RTOp_extract_reduct_obj_state ( const struct RTOp_RTOp op,
const RTOp_ReductTarget  reduct_obj,
int  num_values,
RTOp_value_type  value_data[],
int  num_indexes,
RTOp_index_type  index_data[],
int  num_chars,
RTOp_char_type  char_data[] 
)

Externalize the state of the reduction object to a portable format.

This allows the state of a reduction object to be transported across a heterogeneous network and also allows the use in MPI global reduction operations.

See RTOp_obj_type_vtbl_t for a description of this function.

Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 280 of file RTOp.c.

int RTOp_load_reduct_obj_state ( const struct RTOp_RTOp op,
int  num_values,
const RTOp_value_type  value_data[],
int  num_indexes,
const RTOp_index_type  index_data[],
int  num_chars,
const RTOp_char_type  char_data[],
RTOp_ReductTarget  reduct_obj 
)

Load the state of the reduction object from a portable format.

Note that reduct_obj must be constructed prior to this and therefore the input data must be compatible with the already constructed reduct_obj object.

See RTOp_obj_type_vtbl_t for a description of this function.

Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 307 of file RTOp.c.

int RTOp_coord_invariant ( const struct RTOp_RTOp op,
int *  coord_invariant 
)

Return if the operator is coordinate invariant.

Parameters
coord_invarient[out] If op is coordinate invarient then *coord_invariant will be true.
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 341 of file RTOp.c.

int RTOp_apply_op ( const struct RTOp_RTOp op,
const int  num_vecs,
const struct RTOp_SubVector  sub_vecs[],
const int  num_targ_vecs,
const struct RTOp_MutableSubVector  targ_sub_vecs[],
RTOp_ReductTarget  reduct_obj 
)

op(sub_vecs[],targ_sub_vecs[]),reduct_obj) -> targ_sub_vecs[],reduct_obj.

This is the bread and butter of the whole design. Through this method, a vector implementation applies a reduction/transformation operator to a set of sub-vectors.

Preconditions:

  • num_vecs > 0 || num_targ_vecs > 0
  • num_vecs > 0 || sub_vecs == NULL
  • num_targ_vecs > 0 || targ_sub_vecs == NULL
  • [num_vecs > 0] global_offset == sub_vecs[k].global_offset , for k = 1,...,num_vecs
  • [num_targ_vecs > 0] global_offset == targ_sub_vecs[k].global_offset , for k = 1,...,num_targ_vecs
  • [num_vecs > 0] sub_dim == sub_vecs[k].sub_dim , for k = 1,...,num_vecs
  • [num_targ_vecs > 0] sub_dim == targ_sub_vecs[k].sub_dim , for k = 1,...,num_targ_vecs
Parameters
op[in] Reduction/transformation operator to apply over the sub-vectors.
num_vecs[in] Number of non-mutable sub-vectors sub_vec[*].
sub_vecs[in] Array (length num_vecs) of non-mutable vectors to apply the operator over. The ordering of these sub-vectors sub_vecs[k], for k = 0...num_vecs-1, is significant to the op object. If num_vecs == 0 then sub_vecs can be NULL.
num_targ_vecs[in] Number of mutable sub-vectors targ_sub_vec[*].
targ_sub_vecs[in] Array (length num_targ_vecs) of mutable vectors to apply the operator over and be mutated. The ordering of these sub-vectors targ_sub_vecs[k], for k = 0...num_targ_vecs-1, is significant to the op object. If num_targ_vecs == 0 then targ_sub_vecs can be NULL.
reduct_obj[in/out] This reduction object must have been created by the ::RTOp_reduct_obj_create<tt>(op,reduct_obj) function and it may have already passed through one or more other reduction operations (accumulating the reductions along the way). The reduction operation will be:

op(op(sub_vecs[],targ_sub_vecs[]),reduct_obj) -> reduct_obj

By allowing an in/out reduct_obj and an accumulation of the reduction, the maximum reuse of memory is achieved. If RTOp_reduct_obj_create(op,reduct_obj) or ::RTOp_reduct_obj_reinit<tt>(op,reduct_obj) was called immediately before this function, then reduct_obj will of course only contain the reduction from this operation. If RTOp_get_reduct_type_num_entries(...) returns num_values == 0, num_indexes == 0 and num_chars == 0 then reduct_obj should be set to RTOp_REDUCT_OBJ_NULL and no reduction will be performed.

Returns
Returns 0 if the operation was successfully executed. If num_vecs is incompatible with the underlying operator object then RTOp_ERR_INVALID_NUM_VECS is returned and the operation is not performed. If num_targ_vecs is incompatible with the underlying operator object then RTOp_ERR_INVALID_NUM_TARG_VECS is returned and the operation is not performed. If the sub-vectors are not compatible (i.e. global_offset and/or sub_dim not the same) then RTOp_ERR_INCOMPATIBLE_VECS is returned.

Definition at line 357 of file RTOp.c.

int RTOp_reduce_reduct_objs ( const struct RTOp_RTOp op,
RTOp_ReductTarget  in_reduct_obj,
RTOp_ReductTarget  inout_reduct_obj 
)

op(in_reduct_obj,inout_reduct_obj) -> inout_reduct_obj.

This function reduces the reduction objects from reduced sub-vectors by the RTOp_apply_op(op...) function or those reduced by prior calls to this function.

If reduct_obj == RTOP_REDUCT_OBJ_NULL after the return of RTOp_reduct_obj_create(op,&reduct_obj), then this function should not be called and if it is called with arguments that are not RTOP_REDUCT_OBJ_NULL then an exception an error value will be returned.

Parameters
op[in] The reduction/transformation operation used in the calls to RTOp_apply_op(op,...) and prior calls to this function.
in_reduct_obj[in] A target object from a previous reduction.
inout_reduct_obj[in/out] On input, contains the result from a previous reduction. On output, contains the the reduction of the two target objects.
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 374 of file RTOp.c.

int RTOp_get_reduct_op ( const struct RTOp_RTOp op,
RTOp_reduct_op_func_ptr_t *  reduct_op_func_ptr 
)

Externalize the reduction operation for intermediate target objects.

Parameters
op[in] The reduction operation used in the calls to RTOp_apply_op(op,...).
reduct_op_func_ptr[out] On output, *reduct_op_func_ptr will point to an external reduction function that can be applied to intermediate reduction target objects. This function is MPI compatible and is designed to be used in MPI reduction operations but may be used in other contexts. Any context specific data needed to perform this reduction must be contained in the externalized format of the target objects used with this externalized reduction function. It is allowed for an operator class to return *reduct_op_func_ptr == NULL in which case the client will just have to make due without this function.
Returns
Returns 0 if successful and !=0 otherwise.

Definition at line 385 of file RTOp.c.