class_docstr: Abstract base class for file-based state_dict checkpointing. This class can be used as the base of a checkpointing callback, and handles
  checkpointing frequency logic, checkpoint naming, checkpoint purging / upkeep, and process group synchronization. There are only two methods
  that need to be implemented by subclasses:
  
  1) ``_checkpoint_impl`` which implements the checkpoint saving logic, given the relevant checkpoint items and path.
  2) ``restore`` which implements restoring the checkpoint given the relevant checkpoint path.
  
  The subclass may override the ``metadata_fname`` attribute to specify the filename of the metadata file that will be written within the checkpoint directory.
  This will be used by this base class to ensure the integrity of the checkpoint.
  
  Args:
      dirpath: Parent directory to save checkpoints to.
      save_every_n_train_steps: Frequency of steps with which to save checkpoints during the train epoch. If None, no intra-epoch checkpoints are generated.
      save_every_n_epochs: Frequency of epochs with which to save checkpoints during training. If None, no end-of-epoch checkpoints are generated.
      keep_last_n_checkpoints: Number of most recent checkpoints to keep. If None, all checkpoints are kept. If an excess of existing checkpoints are present, the oldest ones will be deleted to clean the difference.
      process_group: The process group on which the ranks will communicate on. default: ``None`` (the entire world)
  
  Note:
      If torch.distributed is available and default process group is initialized, the constructor will call a collective operation for rank 0 to broadcast the dirpath to all other ranks
  
   Note:
      This class assumes checkpoint items are saved in the directory provided in ``_checkpoint_impl`` and will be in the form of ``<dirpath>/<epoch>-<step>/``. Checkpoint contents
      should be stored within this directory, as deleting and retrieving latest checkpoint relies on reading the <epoch>-<step> directory name within <dirpath>
class_docstr_tok: ["Abstract","base","class","for","file-based","state_dict","checkpointing",".","This","class","can","be","used","as","the","base","of","a","checkpointing","callback",",","and","handles","checkpointing","frequency","logic",",","checkpoint","naming",",","checkpoint","purging","\/","upkeep",",","and","process","group","synchronization",".","There","are","only","two","methods","that","need","to","be","implemented","by","subclasses",":","1",")","``","_checkpoint_impl","``","which","implements","the","checkpoint","saving","logic",",","given","the","relevant","checkpoint","items","and","path",".","2",")","``","restore","``","which","implements","restoring","the","checkpoint","given","the","relevant","checkpoint","path",".","The","subclass","may","override","the","``","metadata_fname","``","attribute","to","specify","the","filename","of","the","metadata","file","that","will","be","written","within","the","checkpoint","directory",".","This","will","be","used","by","this","base","class","to","ensure","the","integrity","of","the","checkpoint",".","Args",":","dirpath",":","Parent","directory","to","save","checkpoints","to",".","save_every_n_train_steps",":","Frequency","of","steps","with","which","to","save","checkpoints","during","the","train","epoch",".","If","None",",","no","intra-epoch","checkpoints","are","generated",".","save_every_n_epochs",":","Frequency","of","epochs","with","which","to","save","checkpoints","during","training",".","If","None",",","no","end-of-epoch","checkpoints","are","generated",".","keep_last_n_checkpoints",":","Number","of","most","recent","checkpoints","to","keep",".","If","None",",","all","checkpoints","are","kept",".","If","an","excess","of","existing","checkpoints","are","present",",","the","oldest","ones","will","be","deleted","to","clean","the","difference",".","process_group",":","The","process","group","on","which","the","ranks","will","communicate","on",".","default",":","``","None","``","(","the","entire","world",")","Note",":","If","torch.distributed","is","available","and","default","process","group","is","initialized",",","the","constructor","will","call","a","collective","operation","for","rank","0","to","broadcast","the","dirpath","to","all","other","ranks","Note",":","This","class","assumes","checkpoint","items","are","saved","in","the","directory","provided","in","``","_checkpoint_impl","``","and","will","be","in","the","form","of","``","<","dirpath",">","\/","<","epoch",">","-","<","step",">","\/","``",".","Checkpoint","contents","should","be","stored","within","this","directory",",","as","deleting","and","retrieving","latest","checkpoint","relies","on","reading","the","<","epoch",">","-","<","step",">","directory","name","within","<","dirpath",">"]
docstr: Implementation for saving checkpoint while taking care of checkpoint
  name generation and cleanup of oldest checkpoints.
  
  Args:
      state: Current state of the trainer.
      unit: Current training unit.
      hook: Hook at which checkpoint is being saved.
  
  Returns:
      True if checkpoint was successfully saved. False otherwise.
docstr_tok: ["Implementation","for","saving","checkpoint","while","taking","care","of","checkpoint","name","generation","and","cleanup","of","oldest","checkpoints",".","Args",":","state",":","Current","state","of","the","trainer",".","unit",":","Current","training","unit",".","hook",":","Hook","at","which","checkpoint","is","being","saved",".","Returns",":","True","if","checkpoint","was","successfully","saved",".","False","otherwise","."]
code: def _generate_checkpoint_and_upkeep(
      self, state: State, unit: TTrainUnit, hook: str
  ) -> bool:
      """
      Implementation for saving checkpoint while taking care of checkpoint
      name generation and cleanup of oldest checkpoints.
  
      Args:
          state: Current state of the trainer.
          unit: Current training unit.
          hook: Hook at which checkpoint is being saved.
  
      Returns:
          True if checkpoint was successfully saved. False otherwise.
      """
      # 1) generate checkpoint name
      num_steps_completed = unit.train_progress.num_steps_completed
      if state.entry_point == EntryPoint.FIT:
          num_steps_completed += cast(
              TEvalUnit, unit
          ).eval_progress.num_steps_completed
      epoch = unit.train_progress.num_epochs_completed
      checkpoint_path = _get_save_path(
          self._dirpath, epoch, num_steps_completed
      )
  
      # 1.5) Ensure the need to checkpoint again at the end of training
      if hook == "on_train_end" and self._does_checkpoint_exist(
          checkpoint_path, self._process_group
      ):
          rank_zero_warn(
              "Final checkpoint already exists, skipping.",
              logger=logger,
          )
          return False
  
      # 2) save checkpoint
      success = self._checkpoint_impl(
          state,
          unit,
          checkpoint_path=checkpoint_path,
          hook=hook,
      )
  
      # 3) book keep and remove oldest checkpoints
      if success:
          if self._should_remove_checkpoint():
              self._remove_checkpoint(state)
          self._ckpt_dirpaths.append(checkpoint_path)
  
      return success
  
imports: import abc
  import logging
  import os
  from typing import Any, cast, Iterable, List, Optional
  import torch.distributed
  from torchtnt.framework.callback import Callback
  from torchtnt.framework.callbacks._checkpoint_utils import _delete_checkpoint, _metadata_exists, get_checkpoint_dirpaths, get_latest_checkpoint_path, rank_zero_read_and_broadcast
  from torchtnt.framework.callbacks.checkpointer_types import RestoreOptions
  from torchtnt.framework.state import EntryPoint, State
  from torchtnt.framework.unit import AppStateMixin, TEvalUnit, TTrainData, TTrainUnit
  from torchtnt.framework.utils import get_timing_context
  from torchtnt.utils.distributed import PGWrapper
  from torchtnt.utils.fsspec import get_filesystem
  from torchtnt.utils.rank_zero_log import rank_zero_warn
label_desc: Use image node_id 4 for calling the BaseCheckpointer obj's underlying member method code with example usage: obj._generate_checkpoint_and_upkeep(state, unit, hook) and returns: success, False