Proposer une amélioration de commentaire

Le commentaire à poster est au format «docblock» (de phpDoc) qui peut être enrichi de tags spécifiques pour SPIP.
Fichier
ecrire/inc/nfslock.php
Fonction
spip_nfsunlock

    Nom ou pseudo de l'auteur de la proposition

Code original

/**
 * Unlock an nfslock()ed file
 *
 * This can get tricky because the lock may have expired (perhaps even
 * during a process that should be "atomic"). We have to make sure we don't
 * unlock some other process' lock, and return a panic code if we think our
 * lock file has been broken illegally. What's done in reaction to that panic
 * (of anything) is up to the caller. See the comments on nfslock()!
 *
 * args: path = path to directory of lock file (/net/u/1/a/alexis/.mailspool)
 *       namelock = file name of lock file (alexis.lock)
 *       max_age = age of lockfile, in seconds, after which the lock is stale.
 *    stale locks are always broken. Defaults to DEFAULT_LOCKTIME
 *    if zero. Panix mail locks go stale at 300 seconds, the default.
 *   birth = time the lock was created (as returned by nfslock()).
 *
 * Returns NFSL_OK if successful, NFSL_LOST if the lock has been lost
 * legitimately (because more than max_age has passed since the lock was
 * created), and NFSL_STOLEN if it's been tampered with illegally (i.e.
 * while this program is within the expiry period). Returns NFSL_SYSF if
 * another system failure prevents it from even trying to unlock the file.
 *
 * Note that for many programs, a return code of NFSL_LOST or NFSL_STOLEN is
 * equally disastrous; a NFSL_STOLEN means that some other program may have
 * trashed your file, but a NFSL_LOST may mean that _you_ have trashed someone
 * else's file (if in fact you wrote the file that you locked after you lost
 * the lock) or that you read inconsistent information.
 *
 * In practice, a return code of NFSL_LOST or NFSL_STOLEN will virtually never
 * happen unless someone is violating the locking protocol.
 *
 * @author Alexis Rosen <alexis@panix.com>
 * @see spip_nfslock()
 *
 * @param string $fichier Chemin du fichier
 * @param bool $birth Timestamp de l'heure de création du verrou
 * @param int $max_age Age maximum du verrou
 * @param bool $test Mode de test
 * return bool true si déverrouillé, false sinon
 */
function spip_nfsunlock($fichier, $birth, $max_age = 0, $test = false) {
	$id = creer_uniqid();
	if (!$max_age) {
		$max_age = _DEFAULT_LOCKTIME;
	}
 
	/*
	 * 1. Build a temp file and stat that to get an idea of what the server
	 *    thinks the current time is (our_tmp.st_ctime)..
	 */
 
	$tpath = _DIR_TMP . "stime.$id";
	$tmpfd = @fopen($tpath, 'w');
	if ((!$tmpfd)
		or (@fputs($tmpfd, 'zz', 2) != 2)
		or !($our_tmp = fstat($tmpfd))
	) {
		/* The open failed, or we can't write the file, or we can't stat it */
		@fclose($tmpfd);
		spip_unlink($tpath);
 
		return false; //(NFSL_SYSF);
	}
 
	@fclose($tmpfd);    /* We don't need this once we have our_tmp.st_ctime. */
	spip_unlink($tpath);
 
	/*
	 * 2. make fullpath, a buffer for the full pathname of the lock file
	 */
 
	$lock_file = _DIR_TMP . _NAME_LOCK . '-' . substr(md5($fichier), 0, 8);
 
	/*
	 * 3. If the ctime hasn't been modified, unlink the file and return. If the
	 *    lock has expired, sleep the usual random interval before returning.
	 *    If we didn't sleep, there could be a race if the caller immediately
	 *    tries to relock the file.
	 */
 
	if (($old_stat = @lstat($lock_file))  /* stat succeeds so file is there */
		&& ($old_stat['ctime'] == $birth)
	) {  /* hasn't been modified since birth */
		if (!$test) {
			spip_unlink($lock_file);
		}      /* so the lock is ours to remove */
		if ($our_tmp['ctime'] >= $birth + $max_age) {  /* the lock has expired */
			if (!$test) {
				return false;
			} //(NFSL_LOST);
			sleep(1 + (random(0, 4)));    /* so sleep a bit */
		}
 
		return true;//(NFSL_OK);			/* success */
	}
 
	/*
	 * 4. Either ctime has been modified, or the entire lock file is missing.
	 *    If the lock should still be ours, based on the ctime of the temp
	 *    file, return with NFSL_STOLEN. If not, then our lock is expired and
	 *    someone else has grabbed the file, so return NFSL_LOST.
	 */
 
	if ($our_tmp['ctime'] < $birth + $max_age) { /* lock was stolen */
		return false;
	} //(NFSL_STOLEN);
 
	return false; //(NFSL_LOST);	/* The lock must have expired first. */
}

Le commentaire au format « docblock » peut être complété des éléments suivants sécifiques
à SPIP.

Sur un entête de fichier :

  • @package SPIP\Core\x (pour un fichier du core, x dépendant du fichier)
  • @package SPIP\Nom\x (pour un fichier de plugin, Nom étant le nom du plugin)

Sur un entête de fonction :

  • @pipeline x : indique que la fonction est une utilisation d’un pipeline
  • @pipeline_appel x : indique que la fonction appelle le pipeline indiqué
  • @balise : indique que la fonction est une compilation de balise
  • @filtre : indique un |filtre
  • @critere : indique que la fonction est une compilaiton de critère
  • @boucle : indique que la fonction est une compilaiton de boucle
Vous inscrire sur ce site

L’espace privé de ce site est ouvert aux visiteurs, après inscription. Une fois enregistré, vous pourrez consulter les articles en cours de rédaction, proposer des articles et participer à tous les forums.

Identifiants personnels

Indiquez ici votre nom et votre adresse email. Votre identifiant personnel vous parviendra rapidement, par courrier électronique.