Spazi dei nomi gestiti

Riepilogo

Introduzione

Gli spazi dei nomi gestiti vengono utilizzati nell'SDK Weave per fornire sia agli sviluppatori dell'SDK Weave sia agli integratori dell'SDK Weave indicazioni e sottotesto pubblicizzati sulla designazione di determinati set di API all'interno dell'SDK, in modo che possano pianificare e prevedere il proprio percorso di migrazione tra le release dell'SDK Weave e, potenzialmente, gestire più API Weave contemporaneamente per un determinato modulo.

Designazione

Gli spazi dei nomi gestiti possono essere gestiti in base a una delle seguenti quattro designazioni:

• Sviluppo
• Avanti
• Attuale
• Precedente

Sviluppo

Qualsiasi spazio dei nomi gestito con la designazione Sviluppo è un'indicazione per sviluppatori e integratori che le API contenute all'interno sono in fase di sviluppo attivo, potrebbero essere soggette a modifiche e non sono ufficialmente supportate. In genere gli integratori non sono autorizzati a utilizzare queste API, a meno che non siano loro specificamente autorizzati a farlo.

Avanti

Qualsiasi spazio dei nomi gestito con la designazione Next è un'indicazione per sviluppatori e integratori che le API contenevano, sebbene abbiano in gran parte completato lo sviluppo attivo, potrebbero essere ancora soggette a modifiche e sono supportate per scopi di valutazione anticipata. Le API così designate rappresentano il prossimo fronte evolutivo in un'API Weave SDK e diventeranno le attuali API predefinite in un ciclo di rilascio più importante nell'immediato e nel prossimo futuro.

Può esistere una compatibilità con le versioni precedenti, sia dal punto di vista dell'API che del protocollo over-the-wire, ma non è garantita nelle API così designate.

La designazione dello spazio dei nomi gestito Next fornisce efficacemente a sviluppatori e integratori una visione della direzione verso l'SDK Weave, suggerendo quella che diventerà l'API predefinita attuale in una release futura.

La designazione dello spazio dei nomi gestito Next è facoltativa, pertanto uno spazio dei nomi gestito può passare attraverso un ciclo di vita senza utilizzarlo (vedi Ciclo di vita dello spazio dei nomi gestito).

Attuale

Qualsiasi spazio dei nomi gestito con la designazione Current o non gestito (ovvero privo di designazione dello spazio dei nomi gestito) rappresenta l'API attuale, predefinita e ufficiale supportata per quella parte o modulo dell'SDK Weave. Anche se potrebbero essere ancora in corso miglioramenti a queste API, le modifiche saranno in gran parte incrementali e compatibili con le versioni precedenti, pertanto è necessario mantenere sia le API che gli over-the-wire.

La designazione dello spazio dei nomi gestito attuale è facoltativa, pertanto uno spazio dei nomi gestito può passare attraverso un ciclo di vita senza utilizzarlo (vedi Ciclo di vita dello spazio dei nomi gestito). Infatti, qualsiasi spazio dei nomi non gestito è implicitamente Current.

Legacy

Qualsiasi spazio dei nomi gestito con la designazione Legacy è un'indicazione per sviluppatori e integratori che le API contenute all'interno sono state deprecate e sono state sostituite da una nuova API attuale. Queste API rappresentano quella che in precedenza era l'API attuale.

Le API così designate scompariranno del tutto alla prossima release principale dell'SDK Weave; di conseguenza, sviluppatori e integratori dovrebbero stabilire dei piani per la migrazione da queste API se intendono rimanere all'avanguardia delle release dell'SDK Weave.

Ciclo di vita dello spazio dei nomi gestito

La figura seguente illustra il ciclo di vita di uno spazio dei nomi gestito durante la transizione da Sviluppo e, potenzialmente, a Legacy:

.-------------.      .- - - .      .- - - - -.      .--------.
| Development | -.->   Next   -.->   Current   ---> | Legacy |
'-------------'  |   '- - - '  |   ' - - - - '      '--------'
                 |             |
                 '-------------'

Se viene utilizzato, il ciclo di vita dello spazio dei nomi gestito inizia con la designazione Sviluppo.

Al termine dello sviluppo e quando il codice è pronto per la valutazione e l'integrazione, la designazione viene migrata a Next o Current. In alternativa, la designazione potrebbe essere eliminata del tutto e lo spazio dei nomi gestito non viene più utilizzato, rendendo di fatto la designazione implicitamente corrente.

Se il codice deve essere integrato e non deve ancora sostituire il codice corrente, la designazione dovrebbe essere migrata a Avanti. Se il codice sostituisce quello attuale, la designazione dovrebbe essere migrata a Current.

Utilizzando la designazione Avanti, dopo che il codice ha raggiunto il numero desiderato di cicli di rilascio e valutazione, la designazione viene migrata a Current o, ancora una volta, la designazione può essere eliminata del tutto.

Utilizzando la designazione "Current", se il codice deve essere sostituito da un nuovo codice, ma deve comunque essere mantenuto per una serie di cicli di rilascio, la designazione viene migrata a Legacy.

Dalla designazione Legacy, il codice viene infine rimosso completamente dall'SDK Weave.

Utilizzo degli spazi dei nomi gestiti

Gli utenti dell'SDK Weave possono interagire con gli spazi dei nomi gestiti in qualità di sviluppatore, estendendo e mantenendo il codice esistente o come integratori, integrando Weave nella propria applicazione, piattaforma e codice di sistema. Le due sezioni seguenti illustrano i suggerimenti per la gestione degli spazi dei nomi gestiti da Weave da questi due punti di vista.

Utilizzo degli spazi dei nomi gestiti come sviluppatore

Uno degli obiettivi principali dello sviluppatore dell'SDK Weave è il miglioramento e lo sviluppo di nuove API e funzionalità dell'SDK Weave e, in molti casi, il supporto delle implementazioni esistenti dell'API e delle funzionalità.

Se non è possibile soddisfare entrambe queste aree in modo compatibile con le versioni precedenti all'interno della stessa API, gli spazi dei nomi gestiti forniscono un meccanismo per gestire queste API in parallelo, in modo da non interrompere i deployment esistenti di API e funzionalità.

Come esempio funzionante, supponiamo che il profilo Weave, Mercury, esista attualmente sotto la seguente gerarchia non gestita dello spazio dei nomi:

namespace nl {
namespace Weave {
namespace Profiles {
namespace Mercury {

// ...

}; // namespace Mercury
}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

e le seguenti intestazioni pubbliche:

• Weave/Profiles/Mercury/Mercury.hpp
• Weave/Profiles/Mercury/Bar.hpp
• Weave/Profiles/Mercury/Foo.hpp
• Weave/Profiles/Mercury/Foobar.hpp

dove Mercury.hpp è l'intestazione "ombrello" del modulo. La maggior parte degli integratori semplicemente include l'intestazione "ombrello" del modulo come mostrato di seguito:

#include 

Tuttavia, lo sviluppatore di Mercury ha ora raggiunto un punto in cui è necessario sviluppare una nuova generazione di API e, potenzialmente, il protocollo over-the-wire che non sono compatibili con le versioni precedenti dei deployment. L'uso degli spazi dei nomi gestiti può aiutarti a raggiungere questo obiettivo senza interrompere i deployment esistenti.

Sposta lo spazio dei nomi esistente su Current

Con l'obiettivo di continuare a supportare la release attuale dell'API e le funzionalità per le integrazioni di cui è stato eseguito il deployment, la prima attività è spostare il codice corrente:

% cd src/lib/profiles/mercury
% mkdir Current
% mv Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp *.cpp Current/

Nota che, oltre a spostare i file, l'intestazione include le protezioni per i file spostati dovrebbe anche essere rinominata, decorandoli potenzialmente con "_CURRENT", poiché i nuovi file con nomi simili verranno creati al loro posto di seguito.

Una volta spostato il codice, il passaggio successivo consiste nel gestire lo spazio dei nomi con la designazione appropriata, qui "Current". Innanzitutto, crea un'intestazione che definisca lo spazio dei nomi gestito, come "Current/MercuryManagedNamespace.hpp". La creazione di un'intestazione di questo tipo è preferibile rispetto alla ripetizione e alla duplicazione di questi contenuti in ciascun file di intestazione quando sono presenti più file di intestazione.

% cat << EOF > Current/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current
#error Compiling Weave Mercury current-designation managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Current
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
EOF

Quindi, includi questa intestazione prima di altre istruzioni di inclusione specifiche per moduli nelle intestazioni esistenti. Ad esempio:

#include 

#include 

Crea intestazioni di compatibilità

Tuttavia, spostare le intestazioni esistenti in una nuova posizione e gestire da solo il loro spazio dei nomi, tuttavia, non è sufficiente per garantire che i deployment esistenti funzionino senza modifiche, poiché utilizzano tutti istruzioni di inclusione che specificano le intestazioni appena spostate in alto.

Per risolvere il problema, è necessario creare intestazioni di wrapper di compatibilità con nomi corrispondenti a quelle appena spostate.

% touch Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp

Se viene creato solo uno spazio dei nomi gestito designato dalla corrente senza creare uno spazio dei nomi gestito designato come Development- o Next da abbinare, i contenuti di questi file possono consistere semplicemente in un'intestazione "include guard" e un'istruzione "include" che specifica l'intestazione con lo stesso nome appena spostata:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Tuttavia, se viene creato anche uno spazio dei nomi gestito designato dallo sviluppo o dal prossimo per far fronte a uno sviluppo nuovo e incompatibile, è necessario fare qualcosa di leggermente più complesso.

Come in precedenza, viene creata un'intestazione per la configurazione dello spazio dei nomi gestito, come MercuryManagedNamespace.hpp. Ancora una volta, è preferibile ripetere e duplicare questi contenuti in ogni file di intestazione quando sono presenti più file di intestazione.

% cat << EOF > MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE)                             \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current) \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development)
#error "WEAVE_CONFIG_MERCURY_NAMESPACE defined, but not as namespace kWeaveManagedNamespace_Current or kWeaveManagedNamespace_Development"
#endif

#if !defined(WEAVE_CONFIG_MERCURY_NAMESPACE)
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
EOF

Tieni presente che, se non è stata definita alcuna configurazione, questo valore predefinito è "Current" come valore dello spazio dei nomi gestito.

Una volta attivata questa intestazione, è possibile modificare le intestazioni dei wrapper di compatibilità in modo da contenere:

#include 

#if WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development
#include 
#else
#include 
#endif // WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development

o a seconda del caso d'uso della gestione dello spazio dei nomi in questione.

Crea contenuti per lo sviluppo

A questo punto, l'infrastruttura è pronta per iniziare a sviluppare nuove funzionalità e API insieme a quelle esistenti.

% mkdir Development
% touch Development/Mercury.hpp Development/Bar.hpp Development/Foo.hpp Development/Foobar.hpp
% cat << EOF > Development/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development
#error Compiling Weave Mercury development-designated managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Development
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Development
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
EOF

Naturalmente, se un modulo è molto più semplice dell'esempio presentato qui e non ha molte classi, origini, file o intestazioni, è possibile eseguire tutte queste operazioni nello stesso file di intestazione senza spostare i file e creare più intestazioni di configurazione e compatibilità indipendenti. Tuttavia, con questo esempio complesso, dovrebbe ispirare soluzioni gestite per lo spazio dei nomi in uno spettro che va dal complesso al semplice.

Utilizzo degli spazi dei nomi gestiti come integratore

Un obiettivo chiave dell'integratore dell'SDK Weave è includere le intestazioni API pubbliche dell'SDK Weave appropriate e l'integrazione e lo sviluppo di applicazioni corrispondenti.

Come esempio funzionante, supponiamo ancora una volta un profilo Weave, Mercury, con spazi dei nomi gestiti designati Next, Current e Legacy, le cui intestazioni pubbliche sono strutturate come segue:

• Weave/Profiles/Mercury/Mercury.hpp
• Weave/Profiles/Mercury/Bar.hpp
• Weave/Profiles/Mercury/Foo.hpp
• Weave/Profiles/Mercury/Foobar.hpp
• Weave/Profiles/Mercury/Next/Mercury.hpp
• Weave/Profiles/Mercury/Next/Bar.hpp
• Weave/Profiles/Mercury/Next/Foo.hpp
• Weave/Profiles/Mercury/Next/Foobar.hpp
• Weave/Profiles/Mercury/Current/Mercury.hpp
• Weave/Profiles/Mercury/Current/Bar.hpp
• Weave/Profiles/Mercury/Current/Foo.hpp
• Weave/Profiles/Mercury/Current/Foobar.hpp
• Weave/Profiles/Mercury/Legacy/Mercury.hpp
• Weave/Profiles/Mercury/Legacy/Bar.hpp
• Weave/Profiles/Mercury/Legacy/Foo.hpp
• Weave/Profiles/Mercury/Legacy/Foobar.hpp

dove Mercury.hpp è l'intestazione "ombrello" del modulo.

A meno che il caso d'uso in questione non supporti esplicitamente l'inclusione di un modulo gestito dallo spazio dei nomi all'interno di Weave, ad esempio:

#include 

è preferibile fare riferimento alle intestazioni pubbliche dei moduli Weave utilizzando i relativi percorsi predefiniti non gestiti (ad es. Weave/Profiles/Mercury/Mercury.hpp). In questo modo è possibile avanzare nello sviluppo delle API senza modificare continuamente le direttive di inclusione di un progetto, man mano che le API scorrono lungo il lifecycle gestito.

Seguendo questa strategia, i deployment possono quindi eseguire il retargeting del loro codice con una designazione diversa dello spazio dei nomi gestito, ad esempio la designazione Current, specificando la configurazione desiderata nel preprocessore C/C++. Questa operazione può essere eseguita nella riga di comando, nel codice sorgente o nell'intestazione di una configurazione o di prefisso:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

e utilizza il percorso di inclusione non gestito / non qualificato:

#include 

Se e quando la designazione dello spazio dei nomi gestito cambia per le API scelte come target, ad esempio da Current a Legacy, è sufficiente eseguire il retargeting regolando la definizione del preprocessore:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy