Provided by: libfabric-dev_1.17.0-3build2_amd64 bug

NAME

       fi_av_set - Address vector set operations

       fi_av_set / fi_close
              Open or close an address vector set

       fi_av_set_union
              Perform a set union operation on two AV sets

       fi_av_set_intersect
              Perform a set intersect operation on two AV sets

       fi_av_set_diff
              Perform a set difference operation on two AV sets

       fi_av_set_insert
              Add an address to an AV set

       fi_av_set_remove
              Remove an address from an AV set

       fi_av_set_addr
              Obtain a collective address for current addresses in an AV set

SYNOPSIS

              #include <rdma/fi_collective.h>

              int fi_av_set(struct fid_av *av, struct fi_av_set_attr *attr,
                    struct fid_av_set **set, void * context);

              int fi_av_set_union(struct fid_av_set *dst, const struct fid_av_set *src);

              int fi_av_set_intersect(struct fid_av_set *dst, const struct fid_av_set *src);

              int fi_av_set_diff(struct fid_av_set *dst, const struct fid_av_set *src);

              int fi_av_set_insert(struct fid_av_set *set, fi_addr_t addr);

              int fi_av_set_remove(struct fid_av_set *set, fi_addr_t addr);

              int fi_av_set_addr(struct fid_av_set *set, fi_addr_t *coll_addr);

              int fi_close(struct fid *av_set);

ARGUMENTS

       av     Address vector

       set    Address vector set

       dst    Address vector set updated by set operation

       src    Address vector set providing input to a set operation

       attr   Address vector set attributes

       context
              User specified context associated with the address vector set

       flags  Additional flags to apply to the operation.

       addr   Destination address to insert to remove from AV set.

       coll_addr
              Address identifying collective group.

DESCRIPTION

       An  address  vector  set  (AV set) represents an ordered subset of addresses of an address
       vector.  AV sets are  used  to  identify  the  participants  in  a  collective  operation.
       Endpoints  use the fi_join_collective() operation to associate itself with an AV set.  The
       join collective operation provides an fi_addr that  is  used  when  communicating  with  a
       collective group.

       The  creation  and  manipulation  of an AV set is a local operation.  No fabric traffic is
       exchanged between peers.  As a result, each peer is responsible for creating  matching  AV
       sets  as  part  of  their  collective  membership  definition.  See fi_collective(3) for a
       discussion of membership models.

   fi_av_set
       The fi_av_set call creates a new AV set.   The  initial  properties  of  the  AV  set  are
       specified  through  the struct fi_av_set_attr parameter.  This structure is defined below,
       and allows including a subset of addresses in the AV set  as  part  of  AV  set  creation.
       Addresses  may  be  added  or  removed  from an AV set using the AV set interfaces defined
       below.

   fi_av_set_attr
              struct fi_av_set_attr {
                  size_t count;
                  fi_addr_t start_addr;
                  fi_addr_t end_addr;
                  uint64_t stride;
                  size_t comm_key_size;
                  uint8_t *comm_key;
                  uint64_t flags;
              };

       count  Indicates the expected the number of members that will be a part  of  the  AV  set.
              The  provider  uses  this  to  optimize  resource  allocations.  If count is 0, the
              provider will select a  size  based  on  available  system  configuration  data  or
              underlying limitations.

       start_addr / end_addr
              The  starting  and  ending  addresses, inclusive, to include as part of the AV set.
              The use of start and end address require that the associated AV have  been  created
              as  type  FI_AV_TABLE.   Valid  addresses in the AV which fall within the specified
              range and which meet other requirements (such as stride) will be added  as  initial
              members to the AV set.  The start_addr and end_addr must be set to FI_ADDR_NOTAVAIL
              if creating an empty AV set, a communication key is being provided, or the AV is of
              type FI_AV_MAP.

       The  number of addresses between start_addr and end_addr must be less than or equal to the
       specified count value.

       stride The number of entries between successive addresses included in the AV set.  The  AV
              set  will  include all addresses from start_addr + stride x i, for increasing, non-
              negative, integer values of i, up to end_addr.  A stride of 1  indicates  that  all
              addresses  between  start_addr  and end_addr should be added to the AV set.  Stride
              should be set to 0 unless the start_addr and end_addr fields are valid.

       comm_key_size
              The length of the communication key  in  bytes.   This  field  should  be  0  if  a
              communication key is not available.

       comm_key
              If  supported by the fabric, this represents a key associated with the AV set.  The
              communication  key  is  used  by  applications  that  directly  manage   collective
              membership  through a fabric management agent or resource manager.  The key is used
              to convey that results of the membership setup to the underlying provider.  The use
              and format of a communication key is fabric provider specific.

       flags  Flags  may  be used to configure the AV set, including restricting which collective
              operations the AV set needs to support.  See the flags section for a list of  flags
              that may be specified when creating the AV set.

   fi_av_set_union
       The  AV  set  union  call  adds  all  addresses  in  the source AV set that are not in the
       destination AV set to the destination AV set.  Where ordering matters, the newly  inserted
       addresses are placed at the end of the AV set.

   fi_av_set_intersect
       The  AV  set  intersect call remove all addresses from the destination AV set that are not
       also members of the source AV set.  The order of the addresses in the destination  AV  set
       is unchanged.

   fi_av_set_diff
       The  AV  set difference call removes all address from the destination AV set that are also
       members of the source AV set.  The order of the addresses in the  destination  AV  set  is
       unchanged.

   fi_av_set_insert
       The AV set insert call appends the specified address to the end of the AV set.

   fi_av_set_remove
       The  AV set remove call removes the specified address from the given AV set.  The order of
       the remaining addresses in the AV set is unchanged.

   fi_av_set_addr
       Returns an address that may be used to communicate with all current members of an AV  set.
       This  is a local operation only that does not involve network communication.  The returned
       address may be used as input into fi_join_collective.  Note that  attempting  to  use  the
       address  returned  from  fi_av_set_addr  (e.g. passing  it  to  fi_join_collective)  while
       simultaneously modifying the addresses stored in an AV set results in undefined behavior.

   fi_close
       Closes an AV set and releases all resources associated with it.  Any operations active  at
       the time an AV set is closed will be aborted, with the result of the collective undefined.

FLAGS

       The following flags may be specified as part of AV set creation.

       FI_UNIVERSE
              When  set,  then  the AV set will be created containing all addresses stored in the
              corresponding AV.

       FI_BARRIER_SET
              If set, the AV set will be configured to support barrier operations.

       FI_BROADCAST_SET
              If set, the AV set will be configured to support broadcast operations.

       FI_ALLTOALL_SET
              If set, the AV set will be configured to support all to all operations.

       FI_ALLREDUCE_SET
              If set, the AV set will be configured to support all reduce operations.

       FI_ALLGATHER_SET
              If set, the AV set will be configured to support all gather operations.

       FI_REDUCE_SCATTER_SET
              If set, the AV set will be configured to support reduce scatter operations.

       FI_REDUCE_SET
              If set, the AV set will be configured to support reduce operations.

       FI_SCATTER_SET
              If set, the AV set will be configured to support scatter operations.

       FI_GATHER_SET
              If set, the AV set will be configured to support gather operations.

NOTES

       Developers who are familiar with MPI will find that AV sets are similar to MPI groups, and
       may act as a direct mapping in some, but not all, situations.

       By default an AV set will be created to support all collective operations supported by the
       underlying provider (see fi_query_collective).  Users may reduce resource requirements  by
       specifying  only  those  collection  operations  needed  by  the AV set through the use of
       creation flags: FI_BARRIER_SET, FI_BROADCAST_SET, etc.  If no such  flags  are  specified,
       the  AV  set  will  be configured to support any that are supported.  It is an error for a
       user to request an unsupported collective.

RETURN VALUES

       Returns 0 on success.  On error,  a  negative  value  corresponding  to  fabric  errno  is
       returned.  Fabric errno values are defined in rdma/fi_errno.h.

SEE ALSO

       fi_av(3), fi_collective(3)

AUTHORS

       OpenFabrics.