Proposed Design/External Interface Design

Owned by Prakash Varandani
Last updated: Dec 05, 2019
7 min read

forum discussion

PP-662 - Getting issue details... STATUS

PP-663 - Getting issue details... STATUS

PP-906 - Getting issue details... STATUS

PP-703 - Getting issue details... STATUS

PP-701 - Getting issue details... STATUS


Interface 1: A new CLI pbs_ralter.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - A new command that will be used for altering reservation attributes.
  4. Details - 
    1. The pbs_ralter command will be used to alter an already submitted advance or standing reservation.
    2. In particular, it can be used to change the start time, end time, mail points, mail_list and the reservation's name.
    3. This command can be used to change an advance reservation or the next/current occurrence of a standing reservation.
    4. After the change is requested, the change is either confirmed or denied.
    5. On denial of the change, the reservation is left as is.
    6. If the user changes only one of the times (start time or end time) of the reservation, the duration of the reservation will change.
    7. This command can be used by the owner of the reservation or the admin to alter any reservation.
    8. If the reservation has not started and if it cannot be reconfirmed on the same nodes, PBS will attempt to look for another set of nodes before denying the request.
    9. Following options will be supported:

      1. Start time modifier: '-R' <start_time>

        1. Specifies reservation's new start time.

        2. This option can be used only when the reservation is not running or is empty i.e. no jobs are submitted to the reservation.

        3. If the change is allowed, reservation will start at the new time specified with this option to pbs_ralter.

        4. The specifications of providing the time are same as pbs_rsub.

      2. End time modifier: '-E' <end_time>

        1. Specifies reservation's new end time.

        2. This option can be used even when the reservation is running and has jobs that are submitted to the reservation.

        3. If the change is confirmed, reservation will end at the new time specified with this option to pbs_ralter.

        4. The specifications of providing the time are same as pbs_rsub.

      3. Interactive option: '-I' <+block_time>.

        1. Specifies interactive mode.

        2. The pbs_ralter command will block, up to <block_time> seconds, while waiting for the reservation's change request to be confirmed.

        3. <block_time> should be positive.

        4. If the change is allowed within <block_time> seconds, pbs_ralter returns with the status “CONFIRMED”.

        5. If the change is denied within  <block_time> seconds, pbs_ralter returns with the status “DENIED”.

        6. If the request cannot be processed within <block_time> seconds, pbs_ralter returns with the status "UNCONFIRMED"

        7. Format: Integer.

        8. Default: Not interactive.

      4. -m <mail_points> 

        1. Works same as pbs_rsub. 

      5. -N reservation_name

        1. Works same as pbs_rsub.

      6. -M mail_list

        1. Works same as pbs_rsub.

      7. -q server
        1. Works same as pbs_rsub.
    10. For standing reservations if the times requested conflict with any of the later occurrences, PBS will deny the alter request with appropriate message on the CLI (Interface 7) and a server log (Interface 14).

Interface 2: CLI response message displayed when a reservation alter could not be confirmed within block_time for interactive option.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - A new CLI response message denoting that the alter request for a reservation could not be confirmed within the block_time provided while using the interactive option of pbs_ralter command.
  4. Details - While using the interactive option, the pbs_ralter command blocks up to block_time seconds while waiting for the reservation's change request to be confirmed. There is a possibility that the request could not be processed within block_time seconds. In that case the command line returns and "pbs_ralter: <resvID> UNCONFIRMED" is displayed on the console.

Interface 3: CLI response message displayed when a reservation alter request is confirmed within block_time for interactive option.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - A new CLI response message denoting that the alter request for a reservation was confirmed within the block_time provided while using the interactive option of pbs_ralter command.
  4. Details - While using the interactive option, the pbs_ralter command blocks up to block_time seconds while waiting for the reservation's change request to be confirmed. If the request is confirmed within block_time seconds, the command line returns and "pbs_ralter: <resvID> CONFIRMED" is displayed on the console.

Interface 4: CLI response message displayed when a reservation alter request is denied within block_time for interactive option.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - A new CLI response message denoting that the alter request for a reservation was denied. Displayed when the interactive option of pbs_ralter command is used.
  4. Details - While using the interactive option, the pbs_ralter command blocks up to block_time seconds while waiting for the reservation's change request to be confirmed. If the request is denied within block_time seconds, the command line returns and "pbs_ralter: <resvID> DENIED" is displayed on the console.

Interface 5: CLI response message displayed in non-interactive mode of pbs_ralter.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - A new CLI response message denoting that an alter request for a reservation is being made.
  4. Details - While using the non-interactive option, the pbs_ralter command returns immediately "pbs_ralter: <resvID> ALTER REQUESTED" is displayed on the console.

Interface 6: A new error code (15178) and a new error message for pbs_ralter denoting that a non-empty reservation that has already started running cannot have its start time altered.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - As per the requirements, reservation in RUNNING state cannot have its start time altered if there are jobs in it.
  4. Details - When pbs_ralter is used for altering its start time that has jobs in it and has already started running, this new error code is returned and "pbs_ralter: Reservation not empty" is displayed on the console.

Interface 7: A new error code (15179) and a new error message for pbs_ralter denoting that the current/next occurrence of a standing reservation being altered interferes with a later occurrence.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - As per the requirements, if the occurrence of a standing reservation being altered will cause a overlap of any later occurrence of the standing reservation being altered, PBS will deny the alter request.
  4. Details - When pbs_ralter is used for altering an occurrence of a standing reservation, and if the requested times cause a overlap of any later occurrence of the standing reservation, this new error code is returned and "pbs_ralter: Requested time(s) will interfere with a later occurrence" is displayed on the console.

Interface 8: A new reservation state denoting that it is being altered (short format).

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - When a reservation alter is being requested in non-interactive mode, until the scheduler confirms/denies the change, the reservation will switch to a new state.
  4. Details - 
    1. When using non-interactive mode of pbs_ralter, the user who has requested the change can check the status of the request by using pbs_rstat. After the request is made, and until the PBS scheduler confirms/denies the change, the reservation will switch to a new state "AL" denoting that it is being altered.
    2. When using non-interactive mode of pbs_ralter, the user who has requested the change can check the status of the request by using pbs_rstat -f. After the request is made, and until the PBS scheduler confirms/denies the change, the reservation will switch to a new state "RESV_BEING_ALTERED" denoting that it is being altered.

Interface 9: Improvement to the 'Y' accounting log.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - The 'Y' accounting record does not have any useful information, so it needs to be improved.
  4. Details - .
    1. When an advance reservation request is confirmed for the first time, 'Y' record will have the format: "Y; <resvID> requestor=Scheduler@<server> start=<requested start time> end=<requested end time> nodes=(<allotted nodes>)".
      1. example - "Y; R123.server requestor=Scheduler@svr start=1497264531 end=1497264651 nodes=(node1:ncpus=3)"
    2. When a standing reservation request is confirmed for the first time, 'Y' record will have the format: "Y; <resvID> requestor=Scheduler@<server> start=<requested start time> end=<requested end time> nodes=(<allotted nodes>) count=<count>". The nodes field will be specific for the first occurrence.
      1. example - "Y; R123.server requestor=Scheduler@svr start=1497264531 end=1497264651 nodes=(node1:ncpus=3) count=3"
    3. This record will be written when an advance reservation alter request is confirmed. The log will have the same format as in point 'a' above, but the requested field(s) will be updated with new value(s): "Y; <resvID> requestor=Scheduler@<server> start=<(new/original) start time> end=<(new/original) end time> nodes=(<allotted nodes>)".
      1. example - "Y; R123.server requestor=root@hostname start=1497264471 end=1497264651 nodes=(node1:ncpus=3)"
    4. This record will be written when a standing reservation alter request is confirmed. The log will have the same format as in point 'b' above, but the requested field(s) will be updated with the new value(s) and index of the next occurrence will be appended. The nodes field will be specific for the occurrence altered: "Y; <resvID> requestor=Scheduler@<server> start=<(new/original) start time> end=<(new/original) end time>  nodes=(<allotted nodes>) count=<count> index=<index of the altered occurrence>".
      1. example - "Y; R123.server requestor=root@hostname start=1497264471 end=1497264651 nodes=(node1:ncpus=3) count=3 index=1"

Interface 10: Improvement to the 'U' accounting log.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - The 'U' accounting record will now have recurrence rule and timezone information for a standing reservation. 'U' record for advance reservation remains unchanged.
  4. Details - .
    1. When a standing reservation is submitted, the 'U' record will now have the format: "U;S56.d_server;requestor=pbsuser@d_server recurrence_rule=FREQ=HOURLY;COUNT=2 timezone=Asia/Kolkata".
      1. example - "U;S56.d_server;requestor=pbsuser@d_server recurrence_rule=FREQ=HOURLY;COUNT=2 timezone=Asia/Kolkata"

Interface 11: A new server log denoting that a reservation alter is being attempted.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - Event type - Reservation, log level - Info.
  4. Details - When a reservation alter is being requested, the PBS server attempts to get a confirmation from the PBS scheduler.
    1. If only start time is being changed, this log will have the format: "Resv;<ResvID>;Attempting to modify reservation start=<requested start time>".
      1. example: "Attempting to modify reservation <resvID> start=1497264471"
    2. If only end time is being changed, this log will have the format: "Resv;<ResvID>;Attempting to modify reservation end=<requested end time>".
      1. example: "Attempting to modify reservation <resvID> end=1497264711"
    3. If both times are being changed, this log will have the format: "Resv;<ResvID>;Attempting to modify reservation start=<requested start time> end=<requested end time>".
      1. example: "Attempting to modify reservation <resvID> start=1497264471 end=1497264711"

Interface 12: A new server log denoting that a reservation alter request is denied/confirmed.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - Event type - Reservation, log level - Info.
  4. Details - 
    1. When a reservation alter request is rejected, server logs this event.
      1. This log will have the format: "Resv;<ResvID>;Reservation alter denied".
    2. When a reservation alter request is confirmed, server logs this event.
      1. This log will have the format: "Resv;<ResvID>;Reservation alter confirmed".

Interface 13: A new server log providing information on a newly submitted reservation.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - Event type - Reservation, log level - Info.
  4. Details - 
    1. When an advance reservation is submitted, server logs this event.
      1. This log will have the format: "Resv;<ResvID>;New reservation submitted start=<requested start time> end=<requested end time>".
    2. When a standing reservation is submitted, server logs this event.
      1. This log will have the format: "Resv;<ResvID>;New reservation submitted start=<requested start time> end=<requested end time> recurrence_rule=<rrule> timezone=<timezone>".

Interface 14: A new server log when a reservation is confirmed/denied.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - Event type - Reservation, log level - Info.
  4. Details - 
    1. When an advance reservation is confirmed, server logs this event.
      1. This log will have the format: "Resv;<ResvID>;Reservation confirmed".
    2. When a standing reservation is denied, server logs this event.
      1. This log will have the format: "Resv;<ResvID>;Reservation denied".

Interface 15: A new server log when the requested timings of the current/next occurrence of the standing reservation being altered would interfere with a later occurrence of the standing reservation being altered, and the request is denied.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - Event type - Reservation, log level - Info.
  4. Details - 
    1. The log will have the format - "Resv;<ResvID>;The requested time(s) would interfere with a later occurrence"

Interface 16: A new PBS IFL API for modifying a reservation.

  1. Visibility - Public
  2. Change Control - Stable
  3. Synopsis - New IFL API.
  4. Details - 
    1. Signature - 

      char * pbs_modify_resv(int server_connect, char *resv_id, struct attropl *attrib, char *extend)

      1. server_connect - socket on which we connect to the server.

      2. resv_id - reservation ID.
      3. attrib - list of attributes to be changed.
      4. extend - for future extensions.