Package uk.ac.manchester.spinnaker.alloc.allocator

Interface SpallocAPI

All Known Implementing Classes:
Spalloc
public interface SpallocAPI
The API of the core service that interacts with the database.
Author:
Donal Fellows

  • Method Details

    • getMachines

      Map<String,​SpallocAPI.Machine> getMachines​(boolean allowOutOfService)
      List the machines.
      Parameters:
      allowOutOfService - Whether to include machines marked as out of service.
      Returns:
      A mapping from names to machines (which are live objects).

    • listMachines

      List<MachineListEntryRecord> listMachines​(boolean allowOutOfService)
      List the machines.
      Parameters:
      allowOutOfService - Whether to include machines marked as out of service.
      Returns:
      A description of all the machines.

    • getMachine

      Optional<SpallocAPI.Machine> getMachine​(@NotNull @NotNull String name, boolean allowOutOfService)
      Get a specific machine.
      Parameters:
      name - The name of the machine to get.
      allowOutOfService - Whether to include machines marked as out of service.
      Returns:
      A machine, on which more operations can be done.

    • getMachineInfo

      Optional<MachineDescription> getMachineInfo​(@NotNull @NotNull String machine, boolean allowOutOfService, Permit permit)
      Get info about a specific machine.
      Parameters:
      machine - The name of the machine to get.
      allowOutOfService - Whether to include machines marked as out of service.
      permit - Encodes what the caller may do.
      Returns:
      A machine description model.

    • getJobs

      SpallocAPI.Jobs getJobs​(boolean deleted, int limit, int start)
      List the jobs.
      Parameters:
      deleted - Whether to include deleted jobs in the list.
      limit - Maximum number of jobs in the returned list. Used for paging.
      start - How many jobs to skip past. Used for paging.
      Returns:
      A list of jobs.

    • listJobs

      List<JobListEntryRecord> listJobs​(Permit permit)
      List the active jobs.
      Parameters:
      permit - Encodes what the caller may do.
      Returns:
      A description of all the active jobs.

    • getJob

      @PostFilter("#permit.admin or #permit.nmpiexec or #permit.name == filterObject.owner.orElse(null)") Optional<SpallocAPI.Job> getJob​(Permit permit, int id)
      Get a specific job. Only owners or admins can see full job details or manipulate the job.
      Parameters:
      permit - Encodes what the caller may do.
      id - The identifier of the job.
      Returns:
      A job object on which more operations can be done, or empty if the job isn't there or isn't available to you.

    • getJobInfo

      @PostFilter("#permit.admin or #permit.nmpiexec or #permit.name == filterObject.owner.orElse(null)") Optional<JobDescription> getJobInfo​(Permit permit, int id)
      Get a specific job. Only owners or admins can see full job details or manipulate the job.
      Parameters:
      permit - Encodes what the caller may do.
      id - The identifier of the job.
      Returns:
      A job description, or empty if the job isn't there (or isn't available to you).

    • createJob

      SpallocAPI.Job createJob​(@NotNull @NotNull String owner, @Valid @Valid SpallocAPI.CreateDescriptor descriptor, String machineName, List<String> tags, Duration keepaliveInterval, byte[] originalRequest) throws IllegalArgumentException
      Create a job for a user that is only in one group. Note that jobs cannot be created on machines that are out of service, but marking a machine as out of service does not stop the jobs that are already running on it.
      Parameters:
      owner - Who is making this job.
      descriptor - What sort of allocation is desired?
      machineName - The name of the machine the user wants to allocate on, or null if they want to select by tags.
      tags - The tags of the machine the user wants to allocate on, or null if they want to select by name.
      keepaliveInterval - The maximum interval between keepalive requests or the job becomes eligible for automated deletion.
      originalRequest - The serialized original request, which will be stored in the database for later retrieval.
      Returns:
      The job created.
      Throws:
      IllegalArgumentException - if the job could not be created.

    • createJobInGroup

      SpallocAPI.Job createJobInGroup​(@NotNull @NotNull String owner, @NotNull @NotNull String group, @Valid @Valid SpallocAPI.CreateDescriptor descriptor, String machineName, List<String> tags, Duration keepaliveInterval, byte[] originalRequest) throws IllegalArgumentException
      Create a job for a user in a specific local group. Note that jobs cannot be created on machines that are out of service, but marking a machine as out of service does not stop the jobs that are already running on it.
      Parameters:
      owner - Who is making this job.
      group - What group is associated with this job for accounting purposes.
      descriptor - What sort of allocation is desired?
      machineName - The name of the machine the user wants to allocate on, or null if they want to select by tags.
      tags - The tags of the machine the user wants to allocate on, or null if they want to select by name.
      keepaliveInterval - The maximum interval between keepalive requests or the job becomes eligible for automated deletion.
      originalRequest - The serialized original request, which will be stored in the database for later retrieval.
      Returns:
      The job created.
      Throws:
      IllegalArgumentException - if the job could not be created.

    • createJobInCollabSession

      SpallocAPI.Job createJobInCollabSession​(@NotNull @NotNull String owner, @NotNull @NotNull String nmpiCollab, @Valid @Valid SpallocAPI.CreateDescriptor descriptor, String machineName, List<String> tags, Duration keepaliveInterval, byte[] originalRequest) throws IllegalArgumentException
      Create a job for interactive use in an NMPI Collab Session. Note that jobs cannot be created on machines that are out of service, but marking a machine as out of service does not stop the jobs that are already running on it.
      Parameters:
      owner - Who is making this job.
      nmpiCollab - The NMPI Collab to manage a session in, and from which the quota will be used.
      descriptor - What sort of allocation is desired?
      machineName - The name of the machine the user wants to allocate on, or null if they want to select by tags.
      tags - The tags of the machine the user wants to allocate on, or null if they want to select by name.
      keepaliveInterval - The maximum interval between keepalive requests or the job becomes eligible for automated deletion.
      originalRequest - The serialized original request, which will be stored in the database for later retrieval.
      Returns:
      The job created.
      Throws:
      IllegalArgumentException - if the job could not be created.

    • createJobForNMPIJob

      @PreAuthorize("hasRole(\'NMPI_EXEC\')") SpallocAPI.Job createJobForNMPIJob​(@NotNull @NotNull String owner, int nmpiJobId, @Valid @Valid SpallocAPI.CreateDescriptor descriptor, String machineName, List<String> tags, Duration keepaliveInterval, byte[] originalRequest) throws IllegalArgumentException
      Create a job for interactive use in an NMPI Collab Session. Note that jobs cannot be created on machines that are out of service, but marking a machine as out of service does not stop the jobs that are already running on it.
      Parameters:
      owner - Who is making this job.
      nmpiJobId - The NMPI Job to allocate the quota used to. The collab of the Job will be used for internal accounting purposes.
      descriptor - What sort of allocation is desired?
      machineName - The name of the machine the user wants to allocate on, or null if they want to select by tags.
      tags - The tags of the machine the user wants to allocate on, or null if they want to select by name.
      keepaliveInterval - The maximum interval between keepalive requests or the job becomes eligible for automated deletion.
      originalRequest - The serialized original request, which will be stored in the database for later retrieval.
      Returns:
      The job created.
      Throws:
      IllegalArgumentException - if the job could not be created.

    • purgeDownCache

      void purgeDownCache()
      Purge the cache of what boards are down.

    • reportProblem

      void reportProblem​(@IPAddress @IPAddress String address, HasChipLocation coreLocation, String description, Permit permit)
      Tells the service that there may be a problem with a board at a particular address.
      Parameters:
      address - The IP address of the board. Note that we haven't yet identified which machine has the board.
      coreLocation - Where on the board is the problem. If the problem is at the core level, it's a HasCoreLocation. If the problem is at the board level, this is null.
      description - Optional problem description. May be null.
      permit - Who is making the request.