PROJET AUTOBLOG


®om's blog

Site original : ®om's blog

⇐ retour index

Mise à jour

Mise à jour de la base de données, veuillez patienter...

C++ sans *pointeurs

jeudi 12 janvier 2017 à 19:33

Les pointeurs sont utilisés plus souvent que nécessaire en C++.

Je voudrais présenter ici comment caractériser les utilisations abusives et par quoi les remplacer.

Objectifs

La décision d’utiliser des pointeurs dépend en grande partie de l’API des objets utilisés.

API est à comprendre dans un sens très large : je considère que des classes utilisées dans une autre partie d’une même application exposent une API.

L’objectif est donc de concevoir des API de manière à ce que leur utilisation ne nécessite pas de manipuler de pointeurs, ni même si possible de smart pointers.

Cela peut paraître surprenant, mais c’est en fait ainsi que vous utilisez les classes de la STL ou de Qt : vos méthodes ne retournent jamais un raw pointer ni un smart pointer vers une string nouvellement créée.

De manière générale, vous n’écririez pas ceci :

// STL version
string *getName() {
    return new string("my name");
}

// Qt version
QString *getName() {
    return new QString("my name");
}

ni ceci :

// STL version
shared_ptr<string> getName() {
    return make_shared<string>("my name");
}

// Qt version
QSharedPointer<QString> getName() {
    return QSharedPointer<QString>::create("my name");
}

À la place, vous écririez sûrement :

// STL version
string getName() {
    return "my name";
}

// Qt version
QString getName() {
    return "my name";
}

Notre objectif est d’écrire des classes qui s’utiliseront de la même manière.

Ownership

Il faut distinguer deux types de raw pointers :

  1. ceux qui détiennent l’objet pointé (owning), qui devront être libérés ;
  2. ceux qui ne le détiennent pas (non-owning).

Le plus simple est de les comparer sur un exemple.

Owning

Info *getInfo() {
    return new Info(/* … */);
}

void doSomething() {
    Info *info = getInfo();
    // info must be deleted
}

Ici, nous avons la responsabilité de supprimer info au bon moment.

C’est ce type de pointeurs dont nous voulons nous débarrasser.

Non-owning

void writeDataTo(QBuffer *buffer) {
    buffer->write("c++");
}

void doSomething() {
    QBuffer buffer;
    writeDataTo(&buffer);
}

Ici, le pointeur permet juste de passer l’adresse de l’objet, mais la méthode writeDataTo(…) ne doit pas gérer sa durée de vie : elle ne le détient donc pas.

Cet usage est tout-à-fait légitime, nous souhaitons le conserver.

Pour savoir si un pointeur est owning ou non, il suffit de se poser la question suivante : est-ce que lui affecter nullptr provoquerait une fuite mémoire ?

Pourquoi ?

Voici quelques exemples illustrant pourquoi nous voulons éviter les owning raw pointers.

Fuite mémoire

Il est facile d’oublier de supprimer un pointeur dans des cas particuliers.

Par exemple :

bool parse() {
    Parser *parser = createParser();
    QFile file("file.txt");
    if (!file.open(QIODevice::ReadOnly))
        return false;
    bool result = parser->parse(&file);
    delete parser;
    return result;
    // parser leaked if open failed
}

Ici, si l’ouverture du fichier a échoué, parser ne sera jamais libéré.

L’exemple suivant est encore plus significatif :

Result *execute() {
    // …
    return new Result(/* … */);
}

void doWork() {
    execute();
    // result leaked
}

Appeler une méthode sans s’occuper du résultat peut provoquer des fuites mémoires.

Double suppression

Il est également possible, par inattention, de supprimer plusieurs fois le même pointeur (ce qui entraîne un undefined behavior).

Par exemple, si device fait partie de la liste devices, ce code le supprime deux fois :

delete device;
qDeleteAll(devices);
// device is deleted twice

Utilisation après suppression

L’utilisation d’un pointeur après sa suppression est également indéfinie.

Je vais prendre un exemple réel en Qt.

Supposons qu’une classe DeviceMonitor surveille le branchement de périphériques, et crée pour chacun un objet Device.

Lorsqu’un périphérique est débranché, un signal Qt provoque l’exécution du slot DeviceMonitor::onDeviceLeft(Device *). Nous voulons alors signaler au reste de l’application que le device est parti (signal DeviceMonitor::deviceLeft(Device *)), puis supprimer l’object device correspondant :

void DeviceMonitor::onDeviceLeft(Device *device) {
    emit deviceLeft(device);
    delete device;
    // slots may use the device after its deletion
    // device->deleteLater() not sufficient
}

Mais c’est loin d’être trivial.

Si nous le supprimons immédiatement comme ceci, et qu’un slot est branché à DeviceMonitor::deviceLeft(Device *) en Qt::QueuedConnection, alors il est possible que le pointeur soit déjà supprimé quand ce slot sera exécuté.

Un proverbe dit que quand ça crashe avec un delete, “il faut appeller deleteLater() pour corriger le problème” :

device->deleteLater();

Mais malheureusement, ici, c’est faux : si le slot branché au signal DeviceMonitor::deviceLeft(Device *) est associé à un QObject vivant dans un autre thread, rien ne garantit que son exécution aura lieu avant la suppression du pointeur.

L’utilisation des owning raw pointers n’est donc pas seulement vulnérable aux erreurs d’inattention (comme dans les exemples précédents) : dans des cas plus complexes, il devient difficile de déterminer quand supprimer le pointeur.

Responsabilité

De manière plus générale, lorsque nous avons un pointeur, nous ne savons pas forcément qui a la responsabilité de le supprimer, ni comment le supprimer :

Data *data = getSomeData();
delete data; // ?
free(data); // ?
custom_deleter(data); // ?

Qt fournit un mécanisme pour supprimer automatiquement les QObject * quand leur parent est détruit. Cependant, cette fonctionnalité ne s’applique qu’aux relations de composition.

Résumons les inconvénients des owning raw pointeurs :

Valeurs

Laissons de côté les pointeurs quelques instants pour observer ce qu’il se passe avec de simples valeurs (des objets plutôt que des pointeurs vers des objets) :

struct Vector {
    int x, y, z;
};

Vector transform(const Vector &v) {
    return { -v.x, v.z, v.y };
}

void compute() {
    Vector vector = transform({ 1, 2, 3 });
    emit finished(transform(vector));
}

C’est plus simple : la gestion mémoire est automatique, et le code est plus sûr. Par exemple, les fuites mémoire et les double suppressions sont impossibles.

Ce sont des avantages dont nous souhaiterions bénéficier également pour les pointeurs.

Privilégier les valeurs

Dans les cas où les pointeurs sont utilisés uniquement pour éviter de retourner des copies (et non pour partager des objets), il est préférable de retourner les objets par valeur à la place.

Par exemple, si vous avez une classe :

struct Result {
    QString message;
    int code;
};

Évitez :

Result *execute() {
    // …
    return new Result { message, code };
}

Préférez :

Result execute() {
    // …
    return { message, code };
}

Certes, dans certains cas, il est moins efficace de passer un objet par valeur qu’à travers un pointeur (car il faut le copier).

Mais cette inefficacité est à relativiser.

D’abord parce que dans certains cas (quand l’objet est copié à partir d’une rvalue reference), la copie sera remplacée par un move. Le move d’un vector par exemple n’entraîne aucune copie (ni move) de ses éléments.

Ensuite parce que les compilateurs optimisent le retour par valeur (RVO), ce qui fait qu’en réalité dans les exemples ci-dessus, aucun Result ni Vector n’est jamais copié ni mové : ils sont directement créés à l’endroit où ils sont affectés (sauf si vous compilez avec le paramètre -fno-elide-constructors).

Mais évidemment, il y a des cas où nous ne pouvons pas simplement remplacer un pointeur par une valeur, par exemple quand un même objet doit être partagé entre différentes parties d’un programme.

Nous voudrions les avantages des valeurs également pour ces cas-là. C’est l’objectif de la suite du billet.

Idiomes C++

Pour y parvenir, nous avons besoin de faire un détour par quelques idiomes couramment utilisés en C++.

Ils ont souvent un nom étrange. Par exemple :

Nous allons étudier les deux premiers.

RAII

Prenons un exemple simple :

bool submit() {
    if (!validate())
        return false;
    return something();
}

Nous souhaitons rendre cette méthode thread-safe grâce à un mutex (std::mutex en STL ou QMutex en Qt).

Supposons que validate() et something() puissent lever une exception.

Le mutex doit être déverrouillé à la fin de l’exécution de la méthode. Le problème, c’est que cela peut se produire à différents endroits, donc nous devons gérer tous les cas :

bool submit() {
    mutex.lock();
    try {
        if (!validate()) {
            mutex.unlock();
            return false;
        }
        bool result = something();
        mutex.unlock();
        return result;
    } catch (...) {
        mutex.unlock();
        throw;
    }
}

Le code est beaucoup plus complexe et propice aux erreurs.

Avec des classes utilisant RAII (std::lock_guard en STL ou QMutexLocker en Qt), c’est beaucoup plus simple :

bool submit() {
    QMutexLocker locker(&mutex);
    if (!validate())
        return false;
    return something();
}

En ajoutant une seule ligne, la méthode est devenue thread-safe.

Cette technique consiste à utiliser le cycle de vie d’un objet pour acquérir une ressource dans le constructeur (ici verrouiller le mutex) et la relâcher dans le destructeur (ici le déverrouiller).

Voici une implémentation simplifiée possible de QMutexLocker :

class QMutexLocker {
    QMutex *mutex;
public:
    explicit QMutexLocker(QMutex *mutex) : mutex(mutex) {
        mutex->lock();
    }
    ~QMutexLocker() {
        mutex->unlock();
    }
};

Comme l’objet est détruit lors de la sortie du scope de la méthode (que ce soit par un return ou par une exception survenue n’importe où), le mutex sera toujours déverrouillé.

Au passage, dans l’exemple ci-dessus, nous remarquons que la variable locker n’est jamais utilisée. RAII complexifie donc la détection des variables inutilisées, car le compilateur doit détecter les effets de bords. Mais il s’en sort bien : ici, il n’émet pas de warning.

Smart pointers

Les smart pointers utilisent RAII pour gérer automatiquement la durée de vie des pointeurs. Il en existe plusieurs.

Dans la STL :

Dans Qt :

Scoped pointers

Le smart pointer le plus simple est le scoped pointer. L’idée est vraiment la même que QMutexLocker, sauf qu’au lieu de vérouiller et déverrouiller un mutex, il stocke un raw pointer et le supprime.

En plus de cela, comme tous les smart pointers, il redéfinit certains opérateurs pour pouvoir être utilisé comme un raw pointer.

Par exemple, voici une implémentation simplifiée possible de QScopedPointer :

template <typename T>
class QScopedPointer {
    T *p;
public:
    explicit QScopedPointer(T *p) : p(p) {}
    ~QScopedPointer() { delete p; }
    T *data() const { return p; }
    operator bool() const { return p; }
    T &operator*() const { return *p; }
    T *operator->() const { return p; }
private:
    Q_DISABLE_COPY(QScopedPointer)
};

Et un exemple d’utilisation :

// bad design (owning raw pointer)
DeviceInfo *Device::getDeviceInfo() {
    return new DeviceInfo(/* … */);
}

void Device::printInfo() {
    QScopedPointer<DeviceInfo> info(getDeviceInfo());
    // used like a raw pointer
    if (info) {
        qDebug() << info->getId();
        DeviceInfo copy = *info;
    }
    // automatically deleted
}

Shared pointers

Les shared pointers permettent de partager l’ownership (la responsabilité de suppression) d’une ressource.

Ils contiennent un compteur de références, indiquant le nombre d’instances partageant le même pointeur. Lorsque ce compteur tombe à 0, le pointeur est supprimé (il faut donc éviter les cycles).

En pratique, voici ce à quoi ressemblerait une liste de Devices partagés par des QSharedPointers :

class DeviceList {
    QList<QSharedPointer<Device>> devices;
public:
    QSharedPointer<Device> getDevice(int index) const;
    void add(const QSharedPointer<Device> &device);
    void remove(Device *device);
};
// devices are automatically deleted when necessary

Le partage d’un pointeur découle toujours de la copie d’un shared pointer. C’est la raison pour laquelle getDevice(…) et add(…) manipulent un QSharedPointer.

Le piège à éviter est de créér plusieurs smart pointers indépendants sur le même raw pointer. Dans ce cas, il y aurait deux refcounts à 1 plutôt qu’un refcount à 2, et le pointeur serait supprimé dès la destruction du premier shared pointer, laissant l’autre pendouillant.

Petite parenthèse : la signature des méthodes add et remove sont différentes car une suppression ne nécessite pas de manipuler la durée de vie du Device passé en paramètre.

Refcounted smart pointers are about managing te owned object’s lifetime.

Copy/assign one only when you intend to manipulate the owned object’s lifetime.

Au passage, si en Qt vous passez vos objets de la couche C++ à la couche QML, il faut aussi passer les shared pointers afin de ne pas casser le partage, ce qui implique d’enregistrer le type :

void registerQml() {
    qRegisterMetaType<QSharedPointer<Device>>();
}

Listons donc les avantages des shared pointers :

Cependant, si la gestion mémoire est automatique, elle n’est pas transparente : elle nécessite de manipuler explicitement des QSharedPointer, ce qui est verbeux.

Il est certes possible d’utiliser un alias (typedef) pour atténuer la verbosité :

using DevicePtr = QSharedPointer<Device>;

class DeviceList {
    QList<DevicePtr> devices;
public:
    DevicePtr getDevice(int index) const;
    void add(const DevicePtr &device);
    void remove(Device *device);
};

Mais quoi qu’il en soit, cela reste plus complexe que des valeurs.

Pour aller plus loin, nous allons devoir faire un détour inattendu, par un idiome qui n’a a priori rien à voir.

PImpl

PImpl sert à réduire les dépendances de compilation.

Opaque pointers are a way to hide the implementation details of an interface from ordinary clients, so that the implementation may be changed without the need to recompile the modules using it.

Prenons la classe Person suivante (person.h) :

class Person {
    QString name;
    long birth;
public:
    Person(const QString &name, long birth);
    QString getName() const;
    void setName(const QString &name);
    int getAge() const;
private:
    static long countYears(long from, long to);
};

Elle contient juste un nom et un âge. Elle définit par ailleurs une méthode privée, countYears(…), qu’on imagine appelée dans getAge().

Chaque classe désirant utiliser la classe Person devra l’inclure :

#include "person.h"

Par conséquent, à chaque modification de ces parties privées (qui sont pourtant que des détails d’implémentation), toutes les classes incluant person.h devront être recompilées.

C’est ce que PImpl permet d’éviter, en séparant la classe en deux :

Concrètement, la classe Person précédente est la partie privée. Renommons-la :

class PersonPrivate {
    QString name;
    long birth;
public:
    PersonPrivate(const QString &name, long birth);
    QString getName() const;
    void setName(const QString &name);
    int getAge() const;
private:
    static long countYears(long from, long to);
};

Créons la partie publique, définissant l’interface souhaitée :

class PersonPrivate; // forward declaration
class Person {
    PersonPrivate *d;
public:
    Person(const QString &name, long birth);
    Person(const Person &other);
    ~Person();
    Person &operator=(const Person &other);
    QString getName() const;
    void setName(const QString &name);
    int getAge() const;
};

Elle contient un pointeur vers PersonPrivate, et lui délègue tous les appels.

Évidemment, Person ne doit pas inclure PersonPrivate, sinon nous aurions les mêmes dépendances de compilation, et nous n’aurions rien résolu. Il faut utiliser à la place une forward declaration.

Voici son implémentation :

Person::Person(const QString &name, long birth) :
        d(new PersonPrivate(name, birth)) {}

Person::Person(const Person &other) :
        d(new PersonPrivate(*other.d)) {}

Person::~Person() { delete d; }

Person &Person::operator=(const Person &other) {
    *d = *other.d;
    return *this;
}

QString Person::getName() const {
    return d->getName();
}

void Person::setName(const QString &name) {
    d->setName(name);
}

int Person::getAge() const {
    return d->getAge();
}

Le pointeur vers la classe privée est souvent nommé d car il s’agit d’un d-pointer.

Donc comme prévu, tout cela n’a rien à voir avec notre objectif d’éviter d’utiliser des pointeurs.

Partage

Mais en fait, si. PImpl permet de séparer les classes manipulées explicitement de l’objet réellement modifié :

graph_pimpl

Il y a une relation 1-1 entre la classe publique et la classe privée correspondante. Mais nous pouvons imaginer d’autres cardinalités.

Par exemple, Qt partage implicitement les parties privées d’un grand nombre de classes. Il ne les copie que lors d’une écriture (CoW) :

graph_pimpl_shareddata

Par exemple, lorsqu’une QString est copiée, la même zone mémoire sera utilisée pour les différentes instances, jusqu’à ce qu’une modification survienne.

Cependant, il ne s’agit que d’un détail d’implémentation utilisé pour améliorer les performances. Du point de vue utilisateur, tout se passe comme si les données étaient réellement copiées :

QString s1 = "ABC";
QString s2 = s1;
s2.append("DEF");
Q_ASSERT(s2 == "ABCDEF");
Q_ASSERT(s1 == "ABC");

En d’autres termes, les classes publiques ci-dessus ont une sémantique de valeur.

Resource handles

À la place, nous pouvons décider de partager inconditionnellement la partie privée, y compris après une écriture :

graph_pimpl_shared

Dans ce cas, la classe publique a sémantique d’entité. Elle est qualifiée de resource handle.

C’est bien sûr le cas des smart pointers :

QSharedPointer<Person> p1(new Person("ABC", 42));
QSharedPointer<person> p2 = p1;
p2->setName("DEF");
Q_ASSERT(p1.getName() == "DEF");
Q_ASSERT(p2.getName() == "DEF");

Mais aussi d’autres classes, comme l’API Dom de Qt :

void addItem(const QDomDocument &document, const QDomElement &element) {
    QDomElement root = document.documentElement();
    root.insertAfter(element, {});
    // the document is modified
}

PImpl avec des smart pointers

Tout-à-l’heure, j’ai présenté PImpl en utilisant un owning raw pointer :

class PersonPrivate; // forward declaration
class Person {
    // this is a raw pointer!
    PersonPrivate *d;
public:
    // …
};

Mais en fait, à chaque type de relation correspond un type de smart pointer directement utilisable pour PImpl.

Pour une relation 1-1 classique :

Pour une relation 1-N à sémantique de valeur (CoW) :

Pour une relation 1-N à sémantique d’entité :

Par exemple, donnons à notre classe Person une sémantique d’entité :

class PersonPrivate; // forward declaration
class Person {
    QSharedPointer<PersonPrivate> d;
public:
    Person() = default; // a "null" person
    Person(const QString &name, long birth);
    QString getName() const;
    // shared handles should expose const methods
    void setName(const QString &name) const;
    int getAge() const;
    operator bool() const { return d; }
};

Person se comporte maintenant comme un pointeur.

Person p1("ABC", 42);
Person p2 = p1;
p2.setName("DEF");
Q_ASSERT(p1.getName() == "DEF");
Q_ASSERT(p2.getName() == "DEF");

p1 et p2 sont alors des resource handles vers PersonPrivate :

graph_shared_person

Évidemment, ce n’est pas approprié pour la classe Person, car le comportement est trop inattendu.

Mais je vais présenter un cas réel où ce design est approprié.

En pratique

Pour l’entreprise dans laquelle je suis salarié, j’ai implémenté une fonctionnalité permettant d’utiliser une souris USB branchée sur un PC pour contrôler un téléphone Android connecté en USB.

Concrètement, cela consiste à tranférer (grâce à libusb), à partir du PC, les événements HID reçus de la souris vers le téléphone Android.

J’ai donc (entre autres) créé des resources handles UsbDevice et UsbDeviceHandle qui wrappent les structures C libusb_device et libusb_device_handle, suivant les principes détaillés dans ce billet.

Leur utilisation illustre bien, d’après moi, les bénéfices d’une telle conception.

class UsbDeviceMonitor {
    QList<UsbDevice> devices;
public:
    // …
    UsbDevice getAnyDroid() const;
    UsbDevice getAnyMouse() const;
signals:
    void deviceArrived(const UsbDevice &device);
    void deviceLeft(const UsbDevice &device);
};

UsbDevice peut être retourné par valeur, et passé en paramètre d’un signal par const reference (exactement comme nous le ferions avec un QString).

UsbDevice UsbDeviceMonitor::getAnyMouse() const {
    for (const UsbDevice &device : devices)
        if (device.isMouse())
            return device;
    return {};
}

Si une souris est trouvée dans la liste, on la retourne simplement ; sinon, on retourne un UsbDevicenull”.

void UsbDeviceMonitor::onHotplugDeviceArrived(const UsbDevice &device) {
    devices.append(device);
    emit deviceArrived(device);
}

La gestion mémoire est totalement automatique et transparente. Les problèmes présentés sont résolus.

void registerQml() {
    qRegisterMetaType<UsbDevice>();
}
// QML
function startForwarding() {
    var mouse = usbDeviceMonitor.getAnyMouse()
    var droid = usbDeviceMonitor.getAnyDroid()
    worker = hid.forward(mouse, droid)
}

UsbDevice peut naviguer entre la couche C++ et QML.

bool HID::forward(const UsbDevice &mouse, const UsbDevice &droid) {
    UsbDeviceHandle droidHandle = droid.open();
    if (!droidHandle)
        return false;
    UsbDeviceHandle mouseHandle = mouse.open();
    if (!mouseHandle)
        return false;
    // …
}

Grâce à RAII, les connexions (UsbDeviceHandle) sont fermées automatiquement.

En particulier, si la connexion à la souris échoue, la connexion au téléphone Android est automatiquement fermée.

Résultat

Dans ces différents exemples, new et delete ne sont jamais utilisés, et par construction, la mémoire sera correctement gérée. Ou plus précisément, si un problème de gestion mémoire existe, il se situera dans l’implémentation de la classe elle-même, et non partout où elle est utilisée.

Ainsi, nous manipulons des handles se comportant comme des pointeurs, ayant les mêmes avantages que les valeurs :

Ils peuvent par contre présenter quelques limitations.

Par exemple, ils sont incompatibles avec QObject. En effet, techniquement, la classe d’un resource handle doit pouvoir être copiée (pour supporter le passage par valeur), alors qu’un QObject n’est pas copiable :

QObjects are identities, not values.

Très concrètement, cela implique que UsbDevice ne pourrait pas supporter de signaux (en tout cas, pas directement). C’est d’ailleurs le cas de beaucoup de classes de Qt : par exemple QString et QList n’héritent pas de QObject.

Résumé

auto decide = [=] {
    if (semantics == VALUE) {
        if (!mustAvoidCopies)
            return "just use values";
        return "use PImpl + QSharedDataPointer";
    }
    // semantics == ENTITY
    if (entitySemanticsIsObvious)
        return "use PImpl + QSharedPointer";
    return "use smart pointers explicitly";
};

C’est juste une heuristique…

Conclusion

En suivant ces principes, nous pouvons nous débarrasser des owning raw pointers et des new et delete “nus”. Cela contribue à rendre le code plus simple et plus robuste.

Ce sont d’ailleurs des objectifs qui guident les évolutions du langage C++ :

return 0;

C++ sans *pointeurs

jeudi 12 janvier 2017 à 19:33

Les pointeurs sont utilisés plus souvent que nécessaire en C++.

Je voudrais présenter ici comment caractériser les utilisations abusives et par quoi les remplacer.

Objectifs

La décision d’utiliser des pointeurs dépend en grande partie de l’API des objets utilisés.

API est à comprendre dans un sens très large : je considère que des classes utilisées dans une autre partie d’une même application exposent une API.

L’objectif est donc de concevoir des API de manière à ce que leur utilisation ne nécessite pas de manipuler de pointeurs, ni même si possible de smart pointers.

Cela peut paraître surprenant, mais c’est en fait ainsi que vous utilisez les classes de la STL ou de Qt : vos méthodes ne retournent jamais un raw pointer ni un smart pointer vers une string nouvellement créée.

De manière générale, vous n’écririez pas ceci :

// STL version
string *getName() {
    return new string("my name");
}

// Qt version
QString *getName() {
    return new QString("my name");
}

ni ceci :

// STL version
shared_ptr<string> getName() {
    return make_shared<string>("my name");
}

// Qt version
QSharedPointer<QString> getName() {
    return QSharedPointer<QString>::create("my name");
}

À la place, vous écririez sûrement :

// STL version
string getName() {
    return "my name";
}

// Qt version
QString getName() {
    return "my name";
}

Notre objectif est d’écrire des classes qui s’utiliseront de la même manière.

Ownership

Il faut distinguer deux types de raw pointers :

  1. ceux qui détiennent l’objet pointé (owning), qui devront être libérés ;
  2. ceux qui ne le détiennent pas (non-owning).

Le plus simple est de les comparer sur un exemple.

Owning

Info *getInfo() {
    return new Info(/* … */);
}

void doSomething() {
    Info *info = getInfo();
    // info must be deleted
}

Ici, nous avons la responsabilité de supprimer info au bon moment.

C’est ce type de pointeurs dont nous voulons nous débarrasser.

Non-owning

void writeDataTo(QBuffer *buffer) {
    buffer->write("c++");
}

void doSomething() {
    QBuffer buffer;
    writeDataTo(&buffer);
}

Ici, le pointeur permet juste de passer l’adresse de l’objet, mais la méthode writeDataTo(…) ne doit pas gérer sa durée de vie : elle ne le détient donc pas.

Cet usage est tout-à-fait légitime, nous souhaitons le conserver.

Pour savoir si un pointeur est owning ou non, il suffit de se poser la question suivante : est-ce que lui affecter nullptr provoquerait une fuite mémoire ?

Pourquoi ?

Voici quelques exemples illustrant pourquoi nous voulons éviter les owning raw pointers.

Fuite mémoire

Il est facile d’oublier de supprimer un pointeur dans des cas particuliers.

Par exemple :

bool parse() {
    Parser *parser = createParser();
    QFile file("file.txt");
    if (!file.open(QIODevice::ReadOnly))
        return false;
    bool result = parser->parse(&file);
    delete parser;
    return result;
    // parser leaked if open failed
}

Ici, si l’ouverture du fichier a échoué, parser ne sera jamais libéré.

L’exemple suivant est encore plus significatif :

Result *execute() {
    // …
    return new Result(/* … */);
}

void doWork() {
    execute();
    // result leaked
}

Appeler une méthode sans s’occuper du résultat peut provoquer des fuites mémoires.

Double suppression

Il est également possible, par inattention, de supprimer plusieurs fois le même pointeur (ce qui entraîne un undefined behavior).

Par exemple, si device fait partie de la liste devices, ce code le supprime deux fois :

delete device;
qDeleteAll(devices);
// device is deleted twice

Utilisation après suppression

L’utilisation d’un pointeur après sa suppression est également indéfinie.

Je vais prendre un exemple réel en Qt.

Supposons qu’une classe DeviceMonitor surveille le branchement de périphériques, et crée pour chacun un objet Device.

Lorsqu’un périphérique est débranché, un signal Qt provoque l’exécution du slot DeviceMonitor::onDeviceLeft(Device *). Nous voulons alors signaler au reste de l’application que le device est parti (signal DeviceMonitor::deviceLeft(Device *)), puis supprimer l’object device correspondant :

void DeviceMonitor::onDeviceLeft(Device *device) {
    emit deviceLeft(device);
    delete device;
    // slots may use the device after its deletion
    // device->deleteLater() not sufficient
}

Mais c’est loin d’être trivial.

Si nous le supprimons immédiatement comme ceci, et qu’un slot est branché à DeviceMonitor::deviceLeft(Device *) en Qt::QueuedConnection, alors il est possible que le pointeur soit déjà supprimé quand ce slot sera exécuté.

Un proverbe dit que quand ça crashe avec un delete, “il faut appeller deleteLater() pour corriger le problème” :

device->deleteLater();

Mais malheureusement, ici, c’est faux : si le slot branché au signal DeviceMonitor::deviceLeft(Device *) est associé à un QObject vivant dans un autre thread, rien ne garantit que son exécution aura lieu avant la suppression du pointeur.

L’utilisation des owning raw pointers n’est donc pas seulement vulnérable aux erreurs d’inattention (comme dans les exemples précédents) : dans des cas plus complexes, il devient difficile de déterminer quand supprimer le pointeur.

Responsabilité

De manière plus générale, lorsque nous avons un pointeur, nous ne savons pas forcément qui a la responsabilité de le supprimer, ni comment le supprimer :

Data *data = getSomeData();
delete data; // ?
free(data); // ?
custom_deleter(data); // ?

Qt fournit un mécanisme pour supprimer automatiquement les QObject * quand leur parent est détruit. Cependant, cette fonctionnalité ne s’applique qu’aux relations de composition.

Résumons les inconvénients des owning raw pointeurs :

Valeurs

Laissons de côté les pointeurs quelques instants pour observer ce qu’il se passe avec de simples valeurs (des objets plutôt que des pointeurs vers des objets) :

struct Vector {
    int x, y, z;
};

Vector transform(const Vector &v) {
    return { -v.x, v.z, v.y };
}

void compute() {
    Vector vector = transform({ 1, 2, 3 });
    emit finished(transform(vector));
}

C’est plus simple : la gestion mémoire est automatique, et le code est plus sûr. Par exemple, les fuites mémoire et les double suppressions sont impossibles.

Ce sont des avantages dont nous souhaiterions bénéficier également pour les pointeurs.

Privilégier les valeurs

Dans les cas où les pointeurs sont utilisés uniquement pour éviter de retourner des copies (et non pour partager des objets), il est préférable de retourner les objets par valeur à la place.

Par exemple, si vous avez une classe :

struct Result {
    QString message;
    int code;
};

Évitez :

Result *execute() {
    // …
    return new Result { message, code };
}

Préférez :

Result execute() {
    // …
    return { message, code };
}

Certes, dans certains cas, il est moins efficace de passer un objet par valeur qu’à travers un pointeur (car il faut le copier).

Mais cette inefficacité est à relativiser.

D’abord parce que dans certains cas (quand l’objet est copié à partir d’une rvalue reference), la copie sera remplacée par un move. Le move d’un vector par exemple n’entraîne aucune copie (ni move) de ses éléments.

Ensuite parce que les compilateurs optimisent le retour par valeur (RVO), ce qui fait qu’en réalité dans les exemples ci-dessus, aucun Result ni Vector n’est jamais copié ni mové : ils sont directement créés à l’endroit où ils sont affectés (sauf si vous compilez avec le paramètre -fno-elide-constructors).

Mais évidemment, il y a des cas où nous ne pouvons pas simplement remplacer un pointeur par une valeur, par exemple quand un même objet doit être partagé entre différentes parties d’un programme.

Nous voudrions les avantages des valeurs également pour ces cas-là. C’est l’objectif de la suite du billet.

Idiomes C++

Pour y parvenir, nous avons besoin de faire un détour par quelques idiomes couramment utilisés en C++.

Ils ont souvent un nom étrange. Par exemple :

Nous allons étudier les deux premiers.

RAII

Prenons un exemple simple :

bool submit() {
    if (!validate())
        return false;
    return something();
}

Nous souhaitons rendre cette méthode thread-safe grâce à un mutex (std::mutex en STL ou QMutex en Qt).

Supposons que validate() et something() puissent lever une exception.

Le mutex doit être déverrouillé à la fin de l’exécution de la méthode. Le problème, c’est que cela peut se produire à différents endroits, donc nous devons gérer tous les cas :

bool submit() {
    mutex.lock();
    try {
        if (!validate()) {
            mutex.unlock();
            return false;
        }
        bool result = something();
        mutex.unlock();
        return result;
    } catch (...) {
        mutex.unlock();
        throw;
    }
}

Le code est beaucoup plus complexe et propice aux erreurs.

Avec des classes utilisant RAII (std::lock_guard en STL ou QMutexLocker en Qt), c’est beaucoup plus simple :

bool submit() {
    QMutexLocker locker(&mutex);
    if (!validate())
        return false;
    return something();
}

En ajoutant une seule ligne, la méthode est devenue thread-safe.

Cette technique consiste à utiliser le cycle de vie d’un objet pour acquérir une ressource dans le constructeur (ici verrouiller le mutex) et la relâcher dans le destructeur (ici le déverrouiller).

Voici une implémentation simplifiée possible de QMutexLocker :

class QMutexLocker {
    QMutex *mutex;
public:
    explicit QMutexLocker(QMutex *mutex) : mutex(mutex) {
        mutex->lock();
    }
    ~QMutexLocker() {
        mutex->unlock();
    }
};

Comme l’objet est détruit lors de la sortie du scope de la méthode (que ce soit par un return ou par une exception survenue n’importe où), le mutex sera toujours déverrouillé.

Au passage, dans l’exemple ci-dessus, nous remarquons que la variable locker n’est jamais utilisée. RAII complexifie donc la détection des variables inutilisées, car le compilateur doit détecter les effets de bords. Mais il s’en sort bien : ici, il n’émet pas de warning.

Smart pointers

Les smart pointers utilisent RAII pour gérer automatiquement la durée de vie des pointeurs. Il en existe plusieurs.

Dans la STL :

Dans Qt :

Scoped pointers

Le smart pointer le plus simple est le scoped pointer. L’idée est vraiment la même que QMutexLocker, sauf qu’au lieu de vérouiller et déverrouiller un mutex, il stocke un raw pointer et le supprime.

En plus de cela, comme tous les smart pointers, il redéfinit certains opérateurs pour pouvoir être utilisé comme un raw pointer.

Par exemple, voici une implémentation simplifiée possible de QScopedPointer :

template <typename T>
class QScopedPointer {
    T *p;
public:
    explicit QScopedPointer(T *p) : p(p) {}
    ~QScopedPointer() { delete p; }
    T *data() const { return p; }
    operator bool() const { return p; }
    T &operator*() const { return *p; }
    T *operator->() const { return p; }
private:
    Q_DISABLE_COPY(QScopedPointer)
};

Et un exemple d’utilisation :

// bad design (owning raw pointer)
DeviceInfo *Device::getDeviceInfo() {
    return new DeviceInfo(/* … */);
}

void Device::printInfo() {
    QScopedPointer<DeviceInfo> info(getDeviceInfo());
    // used like a raw pointer
    if (info) {
        qDebug() << info->getId();
        DeviceInfo copy = *info;
    }
    // automatically deleted
}

Shared pointers

Les shared pointers permettent de partager l’ownership (la responsabilité de suppression) d’une ressource.

Ils contiennent un compteur de références, indiquant le nombre d’instances partageant le même pointeur. Lorsque ce compteur tombe à 0, le pointeur est supprimé (il faut donc éviter les cycles).

En pratique, voici ce à quoi ressemblerait une liste de Devices partagés par des QSharedPointers :

class DeviceList {
    QList<QSharedPointer<Device>> devices;
public:
    QSharedPointer<Device> getDevice(int index) const;
    void add(const QSharedPointer<Device> &device);
    void remove(Device *device);
};
// devices are automatically deleted when necessary

Le partage d’un pointeur découle toujours de la copie d’un shared pointer. C’est la raison pour laquelle getDevice(…) et add(…) manipulent un QSharedPointer.

Le piège à éviter est de créér plusieurs smart pointers indépendants sur le même raw pointer. Dans ce cas, il y aurait deux refcounts à 1 plutôt qu’un refcount à 2, et le pointeur serait supprimé dès la destruction du premier shared pointer, laissant l’autre pendouillant.

Petite parenthèse : la signature des méthodes add et remove sont différentes car une suppression ne nécessite pas de manipuler la durée de vie du Device passé en paramètre.

Refcounted smart pointers are about managing te owned object’s lifetime.

Copy/assign one only when you intend to manipulate the owned object’s lifetime.

Au passage, si en Qt vous passez vos objets de la couche C++ à la couche QML, il faut aussi passer les shared pointers afin de ne pas casser le partage, ce qui implique d’enregistrer le type :

void registerQml() {
    qRegisterMetaType<QSharedPointer<Device>>();
}

Listons donc les avantages des shared pointers :

Cependant, si la gestion mémoire est automatique, elle n’est pas transparente : elle nécessite de manipuler explicitement des QSharedPointer, ce qui est verbeux.

Il est certes possible d’utiliser un alias (typedef) pour atténuer la verbosité :

using DevicePtr = QSharedPointer<Device>;

class DeviceList {
    QList<DevicePtr> devices;
public:
    DevicePtr getDevice(int index) const;
    void add(const DevicePtr &device);
    void remove(Device *device);
};

Mais quoi qu’il en soit, cela reste plus complexe que des valeurs.

Pour aller plus loin, nous allons devoir faire un détour inattendu, par un idiome qui n’a a priori rien à voir.

PImpl

PImpl sert à réduire les dépendances de compilation.

Opaque pointers are a way to hide the implementation details of an interface from ordinary clients, so that the implementation may be changed without the need to recompile the modules using it.

Prenons la classe Person suivante (person.h) :

class Person {
    QString name;
    long birth;
public:
    Person(const QString &name, long birth);
    QString getName() const;
    void setName(const QString &name);
    int getAge() const;
private:
    static long countYears(long from, long to);
};

Elle contient juste un nom et un âge. Elle définit par ailleurs une méthode privée, countYears(…), qu’on imagine appelée dans getAge().

Chaque classe désirant utiliser la classe Person devra l’inclure :

#include "person.h"

Par conséquent, à chaque modification de ces parties privées (qui sont pourtant que des détails d’implémentation), toutes les classes incluant person.h devront être recompilées.

C’est ce que PImpl permet d’éviter, en séparant la classe en deux :

Concrètement, la classe Person précédente est la partie privée. Renommons-la :

class PersonPrivate {
    QString name;
    long birth;
public:
    PersonPrivate(const QString &name, long birth);
    QString getName() const;
    void setName(const QString &name);
    int getAge() const;
private:
    static long countYears(long from, long to);
};

Créons la partie publique, définissant l’interface souhaitée :

class PersonPrivate; // forward declaration
class Person {
    PersonPrivate *d;
public:
    Person(const QString &name, long birth);
    Person(const Person &other);
    ~Person();
    Person &operator=(const Person &other);
    QString getName() const;
    void setName(const QString &name);
    int getAge() const;
};

Elle contient un pointeur vers PersonPrivate, et lui délègue tous les appels.

Évidemment, Person ne doit pas inclure PersonPrivate, sinon nous aurions les mêmes dépendances de compilation, et nous n’aurions rien résolu. Il faut utiliser à la place une forward declaration.

Voici son implémentation :

Person::Person(const QString &name, long birth) :
        d(new PersonPrivate(name, birth)) {}

Person::Person(const Person &other) :
        d(new PersonPrivate(*other.d)) {}

Person::~Person() { delete d; }

Person &Person::operator=(const Person &other) {
    *d = *other.d;
    return *this;
}

QString Person::getName() const {
    return d->getName();
}

void Person::setName(const QString &name) {
    d->setName(name);
}

int Person::getAge() const {
    return d->getAge();
}

Le pointeur vers la classe privée est souvent nommé d car il s’agit d’un d-pointer.

Donc comme prévu, tout cela n’a rien à voir avec notre objectif d’éviter d’utiliser des pointeurs.

Partage

Mais en fait, si. PImpl permet de séparer les classes manipulées explicitement de l’objet réellement modifié :

graph_pimpl

Il y a une relation 1-1 entre la classe publique et la classe privée correspondante. Mais nous pouvons imaginer d’autres cardinalités.

Par exemple, Qt partage implicitement les parties privées d’un grand nombre de classes. Il ne les copie que lors d’une écriture (CoW) :

graph_pimpl_shareddata

Par exemple, lorsqu’une QString est copiée, la même zone mémoire sera utilisée pour les différentes instances, jusqu’à ce qu’une modification survienne.

Cependant, il ne s’agit que d’un détail d’implémentation utilisé pour améliorer les performances. Du point de vue utilisateur, tout se passe comme si les données étaient réellement copiées :

QString s1 = "ABC";
QString s2 = s1;
s2.append("DEF");
Q_ASSERT(s2 == "ABCDEF");
Q_ASSERT(s1 == "ABC");

En d’autres termes, les classes publiques ci-dessus ont une sémantique de valeur.

Resource handles

À la place, nous pouvons décider de partager inconditionnellement la partie privée, y compris après une écriture :

graph_pimpl_shared

Dans ce cas, la classe publique a sémantique d’entité. Elle est qualifiée de resource handle.

C’est bien sûr le cas des smart pointers :

QSharedPointer<Person> p1(new Person("ABC", 42));
QSharedPointer<person> p2 = p1;
p2->setName("DEF");
Q_ASSERT(p1.getName() == "DEF");
Q_ASSERT(p2.getName() == "DEF");

Mais aussi d’autres classes, comme l’API Dom de Qt :

void addItem(const QDomDocument &document, const QDomElement &element) {
    QDomElement root = document.documentElement();
    root.insertAfter(element, {});
    // the document is modified
}

PImpl avec des smart pointers

Tout-à-l’heure, j’ai présenté PImpl en utilisant un owning raw pointer :

class PersonPrivate; // forward declaration
class Person {
    // this is a raw pointer!
    PersonPrivate *d;
public:
    // …
};

Mais en fait, à chaque type de relation correspond un type de smart pointer directement utilisable pour PImpl.

Pour une relation 1-1 classique :

Pour une relation 1-N à sémantique de valeur (CoW) :

Pour une relation 1-N à sémantique d’entité :

Par exemple, donnons à notre classe Person une sémantique d’entité :

class PersonPrivate; // forward declaration
class Person {
    QSharedPointer<PersonPrivate> d;
public:
    Person() = default; // a "null" person
    Person(const QString &name, long birth);
    QString getName() const;
    // shared handles should expose const methods
    void setName(const QString &name) const;
    int getAge() const;
    operator bool() const { return d; }
};

Person se comporte maintenant comme un pointeur.

Person p1("ABC", 42);
Person p2 = p1;
p2.setName("DEF");
Q_ASSERT(p1.getName() == "DEF");
Q_ASSERT(p2.getName() == "DEF");

p1 et p2 sont alors des resource handles vers PersonPrivate :

graph_shared_person

Évidemment, ce n’est pas approprié pour la classe Person, car le comportement est trop inattendu.

Mais je vais présenter un cas réel où ce design est approprié.

En pratique

Pour l’entreprise dans laquelle je suis salarié, j’ai implémenté une fonctionnalité permettant d’utiliser une souris USB branchée sur un PC pour contrôler un téléphone Android connecté en USB.

Concrètement, cela consiste à tranférer (grâce à libusb), à partir du PC, les événements HID reçus de la souris vers le téléphone Android.

J’ai donc (entre autres) créé des resources handles UsbDevice et UsbDeviceHandle qui wrappent les structures C libusb_device et libusb_device_handle, suivant les principes détaillés dans ce billet.

Leur utilisation illustre bien, d’après moi, les bénéfices d’une telle conception.

class UsbDeviceMonitor {
    QList<UsbDevice> devices;
public:
    // …
    UsbDevice getAnyDroid() const;
    UsbDevice getAnyMouse() const;
signals:
    void deviceArrived(const UsbDevice &device);
    void deviceLeft(const UsbDevice &device);
};

UsbDevice peut être retourné par valeur, et passé en paramètre d’un signal par const reference (exactement comme nous le ferions avec un QString).

UsbDevice UsbDeviceMonitor::getAnyMouse() const {
    for (const UsbDevice &device : devices)
        if (device.isMouse())
            return device;
    return {};
}

Si une souris est trouvée dans la liste, on la retourne simplement ; sinon, on retourne un UsbDevicenull”.

void UsbDeviceMonitor::onHotplugDeviceArrived(const UsbDevice &device) {
    devices.append(device);
    emit deviceArrived(device);
}

La gestion mémoire est totalement automatique et transparente. Les problèmes présentés sont résolus.

void registerQml() {
    qRegisterMetaType<UsbDevice>();
}
// QML
function startForwarding() {
    var mouse = usbDeviceMonitor.getAnyMouse()
    var droid = usbDeviceMonitor.getAnyDroid()
    worker = hid.forward(mouse, droid)
}

UsbDevice peut naviguer entre la couche C++ et QML.

bool HID::forward(const UsbDevice &mouse, const UsbDevice &droid) {
    UsbDeviceHandle droidHandle = droid.open();
    if (!droidHandle)
        return false;
    UsbDeviceHandle mouseHandle = mouse.open();
    if (!mouseHandle)
        return false;
    // …
}

Grâce à RAII, les connexions (UsbDeviceHandle) sont fermées automatiquement.

En particulier, si la connexion à la souris échoue, la connexion au téléphone Android est automatiquement fermée.

Résultat

Dans ces différents exemples, new et delete ne sont jamais utilisés, et par construction, la mémoire sera correctement gérée. Ou plus précisément, si un problème de gestion mémoire existe, il se situera dans l’implémentation de la classe elle-même, et non partout où elle est utilisée.

Ainsi, nous manipulons des handles se comportant comme des pointeurs, ayant les mêmes avantages que les valeurs :

Ils peuvent par contre présenter quelques limitations.

Par exemple, ils sont incompatibles avec QObject. En effet, techniquement, la classe d’un resource handle doit pouvoir être copiée (pour supporter le passage par valeur), alors qu’un QObject n’est pas copiable :

QObjects are identities, not values.

Très concrètement, cela implique que UsbDevice ne pourrait pas supporter de signaux (en tout cas, pas directement). C’est d’ailleurs le cas de beaucoup de classes de Qt : par exemple QString et QList n’héritent pas de QObject.

Résumé

auto decide = [=] {
    if (semantics == VALUE) {
        if (!mustAvoidCopies)
            return "just use values";
        return "use PImpl + QSharedDataPointer";
    }
    // semantics == ENTITY
    if (entitySemanticsIsObvious)
        return "use PImpl + QSharedPointer";
    return "use smart pointers explicitly";
};

C’est juste une heuristique…

Conclusion

En suivant ces principes, nous pouvons nous débarrasser des owning raw pointers et des new et delete “nus”. Cela contribue à rendre le code plus simple et plus robuste.

Ce sont d’ailleurs des objectifs qui guident les évolutions du langage C++ :

return 0;

Commentaires statiques avec Jekyll

lundi 9 janvier 2017 à 18:06

Pour ce blog, j’ai abandonné Wordpress pour Jekyll, un moteur de blog statique.

Ainsi, j’écris mes articles en markdown dans mon éditeur favori, je les commite dans un dépôt git, et je génère le blog avec :

jekyll build

Le contenu hébergé étant statique, les pages ainsi générées à partir des sources sont renvoyées telles quelles.

Ce fonctionnement a beaucoup d’avantages :

Sans commentaires

L’inconvénient, c’est qu’un contenu statique est difficilement conciliable avec le support des commentaires (il faut bien d’une manière ou d’une autre exécuter du code lors de la réception d’un commentaire).

Il y a plusieurs manières de contourner le problème.

Il est par exemple possible d’en déporter la gestion (sur un service en ligne comme Disqus ou un équivalent libre – isso – à héberger soi-même). Ainsi, les commentaires peuvent être chargés séparément par le client en Javascript.

Au lieu de cela, j’ai choisi d’intégrer les commentaires aux sources du blog. Voici comment.

L’objectif est d’une part de pouvoir stocker et afficher les commentaires existants, et d’autre part de fournir aux lecteurs la possibilité d’en soumettre de nouveaux, qui me seront envoyés par e-mail.

Je me suis principalement inspiré du contenu de Jekyll::StaticComments, même si, comme nous allons le voir, je n’utilise pas le plug-in lui-même.

Stockage

L’idée est de stocker les commentaires quelque part dans les sources du site au format YAML.

Le plugin Jekyll::StaticComments nécessite de stocker un fichier par commentaire dans un dossier spécial (_comments) parsé par un script à insérer dans le répertoire _plugins.

Personnellement, je préfère avoir tous les commentaires d’un même post regroupés au sein d’un même fichier. Et pour cela, pas besoin de plug-in : nous pouvons faire correspondre à chaque post dans _posts une liste de commentaires dans _data (un répertoire géré nativement par Jekyll).

Par exemple, ce billet est stocké dans :

_posts/2017-01-09-commentaires-statiques-avec-jekyll.md

Dans l’idéal, je voudrais que les commentaires associés soient stockés dans :

_data/comments-2017-01-09-commentaires-statiques-avec-jekyll.yaml

En pratique, pour des raisons techniques (Jekyll ne donne pas accès au nom du fichier), le nom du fichier ne contient pas le numéro du jour :

_data/comments-2017-01-commentaires-statiques-avec-jekyll.yaml

Il suffit alors de stocker dans ces fichiers les commentaires sous cette forme :

- id: 1
  author: this_is_me
  date: 2017-01-02 10:11:12+01:00
  contents: |
    Bonjour,

    Ceci est un commentaire écrit en _markdown_.
- id: 2
  author: dev42
  author-url: https://github.com
  date: 2017-01-02 12:11:10+01:00
  contents: |
    > Ceci est un commentaire écrit en _markdown_.

    Et ça supporte aussi le [Liquid](https://jekyllrb.com/docs/templates/) :

    {% highlight c %}
    int main() {
        return 0;
    }
    {% endhighlight %}

Pour des exemples réels, voir les sources des commentaires de ce blog.

Affichage

Maintenant que nous avons les données des commentaires, nous devons les afficher.

Il faut d’abord trouver la liste des commentaires associée à la page courante.

Comme nous ne pouvons pas récupérer directement le nom du fichier d’une page, nous devons reconstruire la chaîne à partir de la variable page.id, qui ici vaut :

/2017/01/commentaires-statiques-avec-jekyll

Cette ligne de Liquid :

comments{{ page.id | replace: '/', '-' }}

donne la valeur :

comments-2017-01-commentaires-statiques-avec-jekyll

Nous avons donc tout ce dont nous avons besoin pour créer le template de commentaires (à stocker dans _include/comments.html) :

{% capture commentid %}comments{{ page.id | replace: '/', '-' }}{% endcapture %}
{% if site.data[commentid] %}
<h2 id="comments">Commentaires</h2>
<div class="comments">
    {% for comment in site.data[commentid] %}
        <div id="comment-{{ comment.id }}" class="comment" />
            <div class="comment-author">
                {% if (comment.author-url) %}
                    <a href="{{comment.author-url}}">
                {% endif %}
                {{ comment.author }}
                {% if (comment.author-url) %}
                    </a>
                {% endif %}
            </div>
            <div class="comment-date">
                <a href="#comment-{{ comment.id }}">
                    {{ comment.date | date: "%-d %B %Y, %H:%M" }}
                </a>
            </div>
            <div class="comment-contents">
                {{ comment.contents | liquify | markdownify }}
            </div>
        </div>
    {% endfor %}
</div>

Il suffit alors d’inclure cette page à l’endroit où vous souhaitez insérer les commentaires (typiquement dans _layout/post.html) :

{% include comments.html %}

Formulaire

Pour proposer aux utilisateurs de poster de nouveaux commentaires, il nous faut un formulaire.

À titre d’exemple, voici le mien (intégré à _include/comments.html) :

<h3 class="comment-title">Poster un commentaire</h3>
<form method="POST" action="/comments/submit.php">
    <input type="hidden" name="post_id" value="{{ page.id }}" />
    <input type="hidden" name="return_url" value="{{ page.url }}" />
    <table class="comment-table">
        <tr>
            <th>Nom :</th>
            <td>
                <input type="text" size="25" name="name" />
                <em>(requis)</em>
            </td>
        </tr>
        <tr>
            <th>E-mail :</th>
            <td>
                <input type="text" size="25" name="email" />
                <em>(requis, non publié)</em>
            </td>
        </tr>
        <tr>
            <th>Site web :</th>
            <td>
                <input type="text" size="25" name="url" />
                <em>(optionnel)</em>
            </td>
        </tr>
        <tr>
            <td colspan="2">
                <textarea name="comment" rows="10"></textarea>
            </td>
        </tr>
        <tr>
            <td colspan="2">
                <input class="comment-submit" type="submit" value="Envoyer" />
            </td>
        </tr>
    </table>
</form>

Ce formulaire est affiché sous les commentaires existants.

Traitement

L’action du formulaire précédent pointait sur comments/submit.php. Il nous reste donc à écrire dans ce fichier le code à exécuter lorsqu’un utilisateur envoie un commentaire au serveur.

Ce sera la seule partie “dynamique” du site.

Voici les parties importantes de comments/submit.php (basé sur la version de Jekyll::StaticComments) :

<?php
$DATE_FORMAT = "Y-m-d H:i:sP";
$EMAIL_ADDRESS = "your@email";
$SUBJECT = "Nouveau commentaire";
$COMMENT_SENT = "sent.html";

$msg = "post_id: " . $_POST["post_id"] . "\n";
$msg .= "email: " . $_POST["email"] . "\n";
$msg .= "---\n";
$msg .= "- id: ?\n";
$msg .= "  author: " . $_POST["name"] . "\n";
if ($_POST["url"] !== '')
{
    $msg .= "  author-url: " . $_POST["url"] . "\n";
}
$msg .= "  date: " . date($DATE_FORMAT) . "\n";
$msg .= "  contents: |\n" . $_POST["comment"];

$headers = "From: $EMAIL_ADDRESS\n";
$headers .= "Content-Type: text/plain; charset=utf-8";

if (mail($EMAIL_ADDRESS, $SUBJECT, $msg, $headers))
{
    include $COMMENT_SENT;
}
else
{
    echo "Le commentaire n'a pas pu être envoyé.";
}

Quand un commentaire est envoyé avec succès, la page comments/sent.html est affichée à l’utilisateur.

Ainsi, lorsqu’un commentaire est posté, je reçois un mail :

post_id: /2017/01/commentaires-statiques-avec-jekyll
email: my@email
---
- id: ?
  author: ®om
  author-url: http://blog.rom1v.com
  date: 2017-01-09 19:27:10+01:00
  contents: |
Ceci est un test.

J’ai d’ailleurs ajouté une règle procmail pour que ces mails arrivent dans un dossier dédié.

Je peux alors copier le contenu dans le .yaml correspondant, formatter le commentaire (entre autres l’indenter de 4 espaces, ce qu’on pourrait automatiser), et le commiter.

Résumé

Une fois mis en place, vous devriez donc avoir les fichiers suivants :

Conclusion

Je souhaitais depuis longtemps migrer vers un moteur de blog statique, qui correspond davantage à ma façon d’écrire des articles, et offre beaucoup d’avantages (légèreté, sécurité, maintenance…).

Je suis très content d’y être parvenu sans perdre les commentaires ni la possibilité d’en poster de nouveaux.

Certes, la validation est très manuelle, mais c’est le prix à payer pour avoir des commentaires statiques. Pour un blog avec une fréquence de commentaires assez faible, je pense que ce n’est pas très gênant.

Commentaires statiques avec Jekyll

lundi 9 janvier 2017 à 18:06

Pour ce blog, j’ai abandonné Wordpress pour Jekyll, un moteur de blog statique.

Ainsi, j’écris mes articles en markdown dans mon éditeur favori, je les commite dans un dépôt git, et je génère le blog avec :

jekyll build

Le contenu hébergé étant statique, les pages ainsi générées à partir des sources sont renvoyées telles quelles.

Ce fonctionnement a beaucoup d’avantages :

Sans commentaires

L’inconvénient, c’est qu’un contenu statique est difficilement conciliable avec le support des commentaires (il faut bien d’une manière ou d’une autre exécuter du code lors de la réception d’un commentaire).

Il y a plusieurs manières de contourner le problème.

Il est par exemple possible d’en déporter la gestion (sur un service en ligne comme Disqus ou un équivalent libre – isso – à héberger soi-même). Ainsi, les commentaires peuvent être chargés séparément par le client en Javascript.

Au lieu de cela, j’ai choisi d’intégrer les commentaires aux sources du blog. Voici comment.

L’objectif est d’une part de pouvoir stocker et afficher les commentaires existants, et d’autre part de fournir aux lecteurs la possibilité d’en soumettre de nouveaux, qui me seront envoyés par e-mail.

Je me suis principalement inspiré du contenu de Jekyll::StaticComments, même si, comme nous allons le voir, je n’utilise pas le plug-in lui-même.

Stockage

L’idée est de stocker les commentaires quelque part dans les sources du site au format YAML.

Le plugin Jekyll::StaticComments nécessite de stocker un fichier par commentaire dans un dossier spécial (_comments) parsé par un script à insérer dans le répertoire _plugins.

Personnellement, je préfère avoir tous les commentaires d’un même post regroupés au sein d’un même fichier. Et pour cela, pas besoin de plug-in : nous pouvons faire correspondre à chaque post dans _posts une liste de commentaires dans _data (un répertoire géré nativement par Jekyll).

Par exemple, ce billet est stocké dans :

_posts/2017-01-09-commentaires-statiques-avec-jekyll.md

Dans l’idéal, je voudrais que les commentaires associés soient stockés dans :

_data/comments-2017-01-09-commentaires-statiques-avec-jekyll.yaml

En pratique, pour des raisons techniques (Jekyll ne donne pas accès au nom du fichier), le nom du fichier ne contient pas le numéro du jour :

_data/comments-2017-01-commentaires-statiques-avec-jekyll.yaml

Il suffit alors de stocker dans ces fichiers les commentaires sous cette forme :

- id: 1
  author: this_is_me
  date: 2017-01-02 10:11:12+01:00
  contents: |
    Bonjour,

    Ceci est un commentaire écrit en _markdown_.
- id: 2
  author: dev42
  author-url: https://github.com
  date: 2017-01-02 12:11:10+01:00
  contents: |
    > Ceci est un commentaire écrit en _markdown_.

    Et ça supporte aussi le [Liquid](https://jekyllrb.com/docs/templates/) :

    {% highlight c %}
    int main() {
        return 0;
    }
    {% endhighlight %}

Pour des exemples réels, voir les sources des commentaires de ce blog.

Affichage

Maintenant que nous avons les données des commentaires, nous devons les afficher.

Il faut d’abord trouver la liste des commentaires associée à la page courante.

Comme nous ne pouvons pas récupérer directement le nom du fichier d’une page, nous devons reconstruire la chaîne à partir de la variable page.id, qui ici vaut :

/2017/01/commentaires-statiques-avec-jekyll

Cette ligne de Liquid :

comments{{ page.id | replace: '/', '-' }}

donne la valeur :

comments-2017-01-commentaires-statiques-avec-jekyll

Nous avons donc tout ce dont nous avons besoin pour créer le template de commentaires (à stocker dans _include/comments.html) :

{% capture commentid %}comments{{ page.id | replace: '/', '-' }}{% endcapture %}
{% if site.data[commentid] %}
<h2 id="comments">Commentaires</h2>
<div class="comments">
    {% for comment in site.data[commentid] %}
        <div id="comment-{{ comment.id }}" class="comment" />
            <div class="comment-author">
                {% if (comment.author-url) %}
                    <a href="{{comment.author-url}}">
                {% endif %}
                {{ comment.author }}
                {% if (comment.author-url) %}
                    </a>
                {% endif %}
            </div>
            <div class="comment-date">
                <a href="#comment-{{ comment.id }}">
                    {{ comment.date | date: "%-d %B %Y, %H:%M" }}
                </a>
            </div>
            <div class="comment-contents">
                {{ comment.contents | liquify | markdownify }}
            </div>
        </div>
    {% endfor %}
</div>

Il suffit alors d’inclure cette page à l’endroit où vous souhaitez insérer les commentaires (typiquement dans _layout/post.html) :

{% include comments.html %}

Formulaire

Pour proposer aux utilisateurs de poster de nouveaux commentaires, il nous faut un formulaire.

À titre d’exemple, voici le mien (intégré à _include/comments.html) :

<h3 class="comment-title">Poster un commentaire</h3>
<form method="POST" action="/comments/submit.php">
    <input type="hidden" name="post_id" value="{{ page.id }}" />
    <input type="hidden" name="return_url" value="{{ page.url }}" />
    <table class="comment-table">
        <tr>
            <th>Nom :</th>
            <td>
                <input type="text" size="25" name="name" />
                <em>(requis)</em>
            </td>
        </tr>
        <tr>
            <th>E-mail :</th>
            <td>
                <input type="text" size="25" name="email" />
                <em>(requis, non publié)</em>
            </td>
        </tr>
        <tr>
            <th>Site web :</th>
            <td>
                <input type="text" size="25" name="url" />
                <em>(optionnel)</em>
            </td>
        </tr>
        <tr>
            <td colspan="2">
                <textarea name="comment" rows="10"></textarea>
            </td>
        </tr>
        <tr>
            <td colspan="2">
                <input class="comment-submit" type="submit" value="Envoyer" />
            </td>
        </tr>
    </table>
</form>

Ce formulaire est affiché sous les commentaires existants.

Traitement

L’action du formulaire précédent pointait sur comments/submit.php. Il nous reste donc à écrire dans ce fichier le code à exécuter lorsqu’un utilisateur envoie un commentaire au serveur.

Ce sera la seule partie “dynamique” du site.

Voici les parties importantes de comments/submit.php (basé sur la version de Jekyll::StaticComments) :

<?php
$DATE_FORMAT = "Y-m-d H:i:sP";
$EMAIL_ADDRESS = "your@email";
$SUBJECT = "Nouveau commentaire";
$COMMENT_SENT = "sent.html";

$msg = "post_id: " . $_POST["post_id"] . "\n";
$msg .= "email: " . $_POST["email"] . "\n";
$msg .= "---\n";
$msg .= "- id: ?\n";
$msg .= "  author: " . $_POST["name"] . "\n";
if ($_POST["url"] !== '')
{
    $msg .= "  author-url: " . $_POST["url"] . "\n";
}
$msg .= "  date: " . date($DATE_FORMAT) . "\n";
$msg .= "  contents: |\n" . $_POST["comment"];

$headers = "From: $EMAIL_ADDRESS\n";
$headers .= "Content-Type: text/plain; charset=utf-8";

if (mail($EMAIL_ADDRESS, $SUBJECT, $msg, $headers))
{
    include $COMMENT_SENT;
}
else
{
    echo "Le commentaire n'a pas pu être envoyé.";
}

Quand un commentaire est envoyé avec succès, la page comments/sent.html est affichée à l’utilisateur.

Ainsi, lorsqu’un commentaire est posté, je reçois un mail :

post_id: /2017/01/commentaires-statiques-avec-jekyll
email: my@email
---
- id: ?
  author: ®om
  author-url: http://blog.rom1v.com
  date: 2017-01-09 19:27:10+01:00
  contents: |
Ceci est un test.

J’ai d’ailleurs ajouté une règle procmail pour que ces mails arrivent dans un dossier dédié.

Je peux alors copier le contenu dans le .yaml correspondant, formatter le commentaire (entre autres l’indenter de 4 espaces, ce qu’on pourrait automatiser), et le commiter.

Résumé

Une fois mis en place, vous devriez donc avoir les fichiers suivants :

Conclusion

Je souhaitais depuis longtemps migrer vers un moteur de blog statique, qui correspond davantage à ma façon d’écrire des articles, et offre beaucoup d’avantages (légèreté, sécurité, maintenance…).

Je suis très content d’y être parvenu sans perdre les commentaires ni la possibilité d’en poster de nouveaux.

Certes, la validation est très manuelle, mais c’est le prix à payer pour avoir des commentaires statiques. Pour un blog avec une fréquence de commentaires assez faible, je pense que ce n’est pas très gênant.

Challenge reverse engineering

mardi 21 juillet 2015 à 16:31

Un collègue m’a envoyé récemment le lien vers ce challenge, utilisé pour recruter chez NERD (que je ne connais pas).

Je vous le partage car je l’ai trouvé très intéressant. Le but est de trouver un input qui donne l’output attendu.

Pour info, entre le moment où j’ai eu connaissance du problème et le moment où je l’ai résolu, il s’est écoulé 6 jours. Je n’ai pas travaillé dessus à plein temps, mais ne comptez pas le résoudre en 20 minutes ;-)

Je ne publie ni ma réponse au résultat attendu, ni les explications (ce serait incorrect vis-à-vis des auteurs du challenge). Je fournis par contre à la fin l’input qui donne comme output mon e-mail, ce qui suffit à prouver que j’ai résolu le problème.

Amusez-vous bien !

#include <string.h>

typedef unsigned char u8;
typedef unsigned int u32;

u8 confusion[512]={
0xac,0xd1,0x25,0x94,0x1f,0xb3,0x33,0x28,0x7c,0x2b,0x17,0xbc,0xf6,0xb0,0x55,0x5d,
0x8f,0xd2,0x48,0xd4,0xd3,0x78,0x62,0x1a,0x02,0xf2,0x01,0xc9,0xaa,0xf0,0x83,0x71,
0x72,0x4b,0x6a,0xe8,0xe9,0x42,0xc0,0x53,0x63,0x66,0x13,0x4a,0xc1,0x85,0xcf,0x0c,
0x24,0x76,0xa5,0x6e,0xd7,0xa1,0xec,0xc6,0x04,0xc2,0xa2,0x5c,0x81,0x92,0x6c,0xda,
0xc6,0x86,0xba,0x4d,0x39,0xa0,0x0e,0x8c,0x8a,0xd0,0xfe,0x59,0x96,0x49,0xe6,0xea,
0x69,0x30,0x52,0x1c,0xe0,0xb2,0x05,0x9b,0x10,0x03,0xa8,0x64,0x51,0x97,0x02,0x09,
0x8e,0xad,0xf7,0x36,0x47,0xab,0xce,0x7f,0x56,0xca,0x00,0xe3,0xed,0xf1,0x38,0xd8,
0x26,0x1c,0xdc,0x35,0x91,0x43,0x2c,0x74,0xb4,0x61,0x9d,0x5e,0xe9,0x4c,0xbf,0x77,
0x16,0x1e,0x21,0x1d,0x2d,0xa9,0x95,0xb8,0xc3,0x8d,0xf8,0xdb,0x34,0xe1,0x84,0xd6,
0x0b,0x23,0x4e,0xff,0x3c,0x54,0xa7,0x78,0xa4,0x89,0x33,0x6d,0xfb,0x79,0x27,0xc4,
0xf9,0x40,0x41,0xdf,0xc5,0x82,0x93,0xdd,0xa6,0xef,0xcd,0x8d,0xa3,0xae,0x7a,0xb6,
0x2f,0xfd,0xbd,0xe5,0x98,0x66,0xf3,0x4f,0x57,0x88,0x90,0x9c,0x0a,0x50,0xe7,0x15,
0x7b,0x58,0xbc,0x07,0x68,0x3a,0x5f,0xee,0x32,0x9f,0xeb,0xcc,0x18,0x8b,0xe2,0x57,
0xb7,0x49,0x37,0xde,0xf5,0x99,0x67,0x5b,0x3b,0xbb,0x3d,0xb5,0x2d,0x19,0x2e,0x0d,
0x93,0xfc,0x7e,0x06,0x08,0xbe,0x3f,0xd9,0x2a,0x70,0x9a,0xc8,0x7d,0xd8,0x46,0x65,
0x22,0xf4,0xb9,0xa2,0x6f,0x12,0x1b,0x14,0x45,0xc7,0x87,0x31,0x60,0x29,0xf7,0x73,
0x2c,0x97,0x72,0xcd,0x89,0xa6,0x88,0x4c,0xe8,0x83,0xeb,0x59,0xca,0x50,0x3f,0x27,
0x4e,0xae,0x43,0xd5,0x6e,0xd0,0x99,0x7b,0x7c,0x40,0x0c,0x52,0x86,0xc1,0x46,0x12,
0x5a,0x28,0xa8,0xbb,0xcb,0xf0,0x11,0x95,0x26,0x0d,0x34,0x66,0x22,0x18,0x6f,0x51,
0x9b,0x3b,0xda,0xec,0x5e,0x00,0x2a,0xf5,0x8f,0x61,0xba,0x96,0xb3,0xd1,0x30,0xdc,
0x33,0x75,0xe9,0x6d,0xc8,0xa1,0x3a,0x3e,0x5f,0x9d,0xfd,0xa9,0x31,0x9f,0xaa,0x85,
0x2f,0x92,0xaf,0x67,0x78,0xa5,0xab,0x03,0x21,0x4f,0xb9,0xad,0xfe,0xf3,0x42,0xfc,
0x17,0xd7,0xee,0xa3,0xd8,0x80,0x14,0x2e,0xa0,0x47,0x55,0xc4,0xff,0xe5,0x13,0x3f,
0x81,0xb6,0x7a,0x94,0xd0,0xb5,0x54,0xbf,0x91,0xa7,0x37,0xf1,0x6b,0xc9,0x1b,0xb1,
0x3c,0xb6,0xd9,0x32,0x24,0x8d,0xf2,0x82,0xb4,0xf9,0xdb,0x7d,0x44,0xfb,0x1e,0xd4,
0xea,0x5d,0x35,0x69,0x23,0x71,0x57,0x01,0x06,0xe4,0x55,0x9a,0xa4,0x58,0x56,0xc7,
0x4a,0x8c,0x8a,0xd6,0x6a,0x49,0x70,0xc5,0x8e,0x0a,0x62,0xdc,0x29,0x4b,0x42,0x41,
0xcb,0x2b,0xb7,0xce,0x08,0xa1,0x76,0x1d,0x1a,0xb8,0xe3,0xcc,0x7e,0x48,0x20,0xe6,
0xf8,0x45,0x93,0xde,0xc3,0x63,0x0f,0xb0,0xac,0x5c,0xba,0xdf,0x07,0x77,0xe7,0x4e,
0x1f,0x28,0x10,0x6c,0x59,0xd3,0xdd,0x2d,0x65,0x39,0xb2,0x74,0x84,0x3d,0xf4,0xbd,
0xc7,0x79,0x60,0x0b,0x4d,0x33,0x36,0x25,0xbc,0xe0,0x09,0xcf,0x5b,0xe2,0x38,0x9e,
0xc0,0xef,0xd2,0x16,0x05,0xbe,0x53,0xf7,0xc2,0xc6,0xa2,0x24,0x98,0x1c,0xad,0x04};

u32 diffusion[32]={
0xf26cb481,0x16a5dc92,0x3c5ba924,0x79b65248,0x2fc64b18,0x615acd29,0xc3b59a42,0x976b2584,
0x6cf281b4,0xa51692dc,0x5b3c24a9,0xb6794852,0xc62f184b,0x5a6129cd,0xb5c3429a,0x6b978425,
0xb481f26c,0xdc9216a5,0xa9243c5b,0x524879b6,0x4b182fc6,0xcd29615a,0x9a42c3b5,0x2584976b,
0x81b46cf2,0x92dca516,0x24a95b3c,0x4852b679,0x184bc62f,0x29cd5a61,0x429ab5c3,0x84256b97};

u8 input[32]={
//change only this :
0x66,0xd5,0x4e,0x28,0x5f,0xff,0x6b,0x53,0xac,0x3b,0x34,0x14,0xb5,0x3c,0xb2,0xc6,
0xa4,0x85,0x1e,0x0d,0x86,0xc7,0x4f,0xba,0x75,0x5e,0xcb,0xc3,0x6e,0x48,0x79,0x8f
//
};

void Forward(u8 c[32],u8 d[32],u8 s[512],u32 p[32])
{
    for(u32 i=0;i<256;i++)
    {
        for(u8 j=0;j<32;j++)
        {
            d[j]=s[c[j]];
            c[j]=0;
        }

        for(u8 j=0;j<32;j++)
            for(u8 k=0;k<32;k++)
                c[j]^=d[k]*((p[j]>>k)&1);
    }
    for(u8 i=0;i<16;i++)
        d[i]=s[c[i*2]]^s[c[i*2+1]+256];
}

int main(int argc, char* argv[])
{
    u8 target[]="Hire me!!!!!!!!";
    u8 output[32];

    Forward(input,output,confusion,diffusion);

    return memcmp(output,target,16); // => contact jobs(at)nerd.nintendo.com
}

Ma preuve de solution :

diff --git a/HireMe.cpp b/HireMe.cpp
index ca94719..8374683 100644
--- a/HireMe.cpp
+++ b/HireMe.cpp
@@ -45,8 +45,8 @@ u32 diffusion[32]={
 
 u8 input[32]={
 //change only this :
-0x66,0xd5,0x4e,0x28,0x5f,0xff,0x6b,0x53,0xac,0x3b,0x34,0x14,0xb5,0x3c,0xb2,0xc6,
-0xa4,0x85,0x1e,0x0d,0x86,0xc7,0x4f,0xba,0x75,0x5e,0xcb,0xc3,0x6e,0x48,0x79,0x8f
+0x82,0x69,0xd7,0x3c,0xd7,0x58,0xd7,0x0d,0x22,0x46,0x58,0x22,0x22,0x69,0x22,0x77,
+0x77,0xd7,0x77,0xe6,0xf8,0x22,0xd7,0x58,0x9c,0x58,0x3c,0xf8,0xf8,0x22,0x58,0x13
 //
 };
 
@@ -70,7 +70,7 @@ void Forward(u8 c[32],u8 d[32],u8 s[512],u32 p[32])
 
 int main(int argc, char* argv[])
 {
-   u8 target[]="Hire me!!!!!!!!";
+   u8 target[]="[rom@rom1v.com]";
    u8 output[32];
 
    Forward(input,output,confusion,diffusion);