Constructing and Destroying ResourceBroker Instances

As described previously, to actually make use of a GATHardwareResourceDescription or GATSoftware Description to find or reserve resource one needs to first create a GATResourceBroker. So, before we can train our magnifying glass upon the grid we need to first understand how to create. and subsequently destroy, GATResourceBroker instances.

To create a GATResourceBroker instance one employs the function

GATResourceBroker
  GATResourceBroker_Create(GATContext context, GATPreferences_const preferences,
    GATString vo_name)

The first argument to this function is a GATContext, the details of which we have previously covered. The next argument is a GATPreferences instance, the details of which are covered in Appendix . The final argument to this function is a GATString. This GATString identifies the so called ``virtual organization'' from which this resultant GATResourceBroker can cull resources.

A virtual organization is a ``dynamic collections of individuals, institutions, and resources.'' So, what exactly does that mean? Let's illustrate with an example. A particular organization, for example A.P.E., the Agency to Prevent Evil, would be considered a virtual organization. In addition coalitions of organizations could also be considered as a virtual organization; for example, the coalition of institutions which work together as part of the GridLab project are a virtual organization. In general any organization or umbrella organization is a virtual organization.

The format which the GATString instance that identifies the virtual organization from which this resultant GATResourceBroker can cull resources is as of yet ill defined. Currently there is no standard format which the name of a virtual organization takes. Hence, to maintain maximal flexibility, GAT allows for the application programmer to specify this virtual organization with an arbitrary GATString instance.

Finally the function GATResourceBroker_Create returns a GATResourceBroker corresponding to the passed information. However, it returns NULL if there is a problem in creating the specified GATResourceBroker instance.

As an example of this function is action let us consider the creation of a GATResourceBroker instance for the virtual organization ``www.gridlab.org'' A code snippet which would create such a GATResourceBroker would look as follows

GATString string;
GATContext context;
GATResourceBroker resourceBroker;

context = GATContext_Create();

if( NULL != context )
{
  string = GATString_Create( "www.gridlab.org", 16, "ASCII" );
  
  if( NULL != string )
  {
    resourceBroker = GATResourceBroker_Create( context, NULL, string );
    
    if( NULL != resourceBroker )
    {
      /* Do something! */
    }
  
    GATString_Destroy( &string );
  }
  
  GATContext_Destroy( &context );
}

To destroy such a GATResourceBroker instance and clean up any resources tied up by such an instance one calls the function

void GATResourceBroker_Destroy(GATResourceBroker *resource)

This function takes as its first, and only, argument a pointer to a GATResourceBroker. This points to the GATResourceBroker instance to be destroyed. For example, we can extend the previous code snippet to clean up the GATResourceBroker instance as follows

GATString string;
GATContext context;
GATResourceBroker resourceBroker;

context = GATContext_Create();

if( NULL != context )
{
  string = GATString_Create( "www.gridlab.org", 16, "ASCII" );
  
  if( NULL != string )
  {
    resourceBroker = GATResourceBroker_Create( context, NULL, string );
    
    if( NULL != resourceBroker )
    {
      /* Do something! */
      
      GATResourceBroker_Destroy( &resourceBroker );
    }
  
    GATString_Destroy( &string );
  }
  
  GATContext_Destroy( &context );
}