Reserving Resources Using a Resource Description:

GAT provides the following call to allow for resource reservation using a GATResourceDescription instance

GATResult
  GATResourceBroker_ReserveResource_Description(GATResourceBroker broker,
    GATResourceDescription_const description, GATTime_const time,
    GATTimePeriod_const duration, GATReservation *reservation)

The initial argument to this function is the GATResourceBroker instance which is used to call in the reservation. The next argument is a GATResourceDescription instance used to describe the the desired resource. The following argument is a GATTime instances, the details of which are covered in Chapter , which indicates the time at which this reservation should start. The very next argument is a GATTimePeriod, a class which we will cover below, that signal the duration of this reservation. For example, a reservation may start on 00:00 GMT June 6 2020 and last for 24 hours.

This class GATTimePeriod, as one may gather from above, specifies a period of time. One creates an instance of such a class using the function

GATTimePeriod GATTimePeriod_Create(GATdouble64 duration)

This function will, upon success, return a GATTimePeriod instance which represents a period of time duration seconds long. If this call fails it returns NULL. One can also create an instance using the function

GATTimePeriod GATTimePeriod_Create_Difference(GATTime start, GATTime end)

which upon success creates a GATTimePeriod that starts at start and ends at end. One destroys such an instance using the function

void GATTimePeriod_Destroy(GATTimePeriod *resource)

which releases all resource held by the passed GATTimePeriod instance. Finally one can examine the duration represented by a GATTimePeriod instance through a call to the function

GATdouble64 GATTimePeriod_GetDuration(GATTimePeriod_const period

which returns the duration in seconds represented by the GATTimePeriod instance period.

The final argument to the function GATResourceBroker_ReserveResource_Description is a pointer to a GATReservation. It is through this pointer that the function returns to the caller an instance of the class GATReservation which represents a reservation.

The application programmer can not directly create an instance of the class GATReservation. An application programmer can only obtain such instances through calls of the above ilk. The application programmer is, however, responsible for destroying such GATReservation instances. This is done through a call to the function

void GATReservation_Destroy(GATReservation *resource)

which releases any resources held be the passed GATReservation instance. After obtaining such a GATReservation instance one can obtain the GATResource to which this GATReservation corresponds through the call

GATResult GATReservation_GetResource(GATReservation_const reservation, 
                                     GATResource_const *resource)

Finally we complete our study of the original function GATResourceBroker_ReserveResource_ Description by noting that it returns a GATResult, covered in Appendix , which indicates the completion status of the function.