Spazi dei nomi gestiti

Riepilogo

Introduzione

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

Designazione

Gli spazi dei nomi gestiti possono essere gestiti secondo una di quattro classificazioni:

• Sviluppo
• Avanti
• Attuale
• Precedente

Sviluppo

Lo spazio dei nomi gestito con la designazione Sviluppo indica a sviluppatori e integratori che le API contenute al loro interno sono in fase di sviluppo attivo, potrebbero essere soggette a modifiche e non sono ufficialmente supportate. Generalmente, agli integratori viene sconsigliato utilizzare queste API, a meno che non sia espressamente indicato.

Avanti

Lo spazio dei nomi gestito con la designazione Next indica a sviluppatori e integratori che le API contenute al loro interno, anche se hanno in gran parte completato lo sviluppo attivo, possono 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 dell'SDK Weave e diventeranno le attuali API predefinite in un importante ciclo di rilasci nell'immediato o nell'immediato futuro.

È possibile che esista una compatibilità con le versioni precedenti sia dal punto di vista delle API che del protocollo over-the-wire, ma non è garantita nelle API così designate.

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

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

Attuale

Lo spazio dei nomi gestito con la designazione Current o qualsiasi spazio dei nomi non gestito (ovvero senza una 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 di compatibilità con le versioni precedenti. È necessario mantenere sia l'API che la tecnologia over-the-wire.

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

Legacy

Lo spazio dei nomi gestito con la designazione Legacy indica a sviluppatori e integratori che le API contenute al loro 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 successiva release principale dell'SDK Weave; di conseguenza, sviluppatori e integratori dovrebbero definire 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 a Legacy:

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

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

Una volta completato lo sviluppo e il codice è pronto per la valutazione e l'integrazione, la designazione viene migrata in Successivo o Corrente. In alternativa, la designazione può essere eliminata del tutto e lo spazio dei nomi gestito non viene più utilizzato, rendendola implicitamente corrente.

Se il codice deve essere integrato e non deve essere ancora sostituito dal codice attuale, la designazione deve passare a Next. Se il codice deve sostituire il codice attuale, la designazione deve passare a Current.

Utilizzando la designazione Next, dopo che il codice ha subito il numero desiderato di cicli di rilascio e valutazione, la designazione viene trasferita in Current o, di nuovo, la designazione può essere eliminata del tutto.

Utilizzando la designazione Current, se il codice deve essere soppiantato da nuovo codice, ma deve comunque essere mantenuto per una serie di cicli di rilascio, la designazione viene trasferita nella versione precedente.

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 come sviluppatore, estendendo e mantenendo il codice esistente oppure come integratore, integrando Weave nella propria applicazione, nella propria piattaforma e nel proprio codice di sistema. Le due sezioni riportate di seguito illustrano in dettaglio i consigli per la gestione degli spazi dei nomi gestiti da Weave da questi due punti di vista.

Utilizzo degli spazi dei nomi gestiti come sviluppatore

Un obiettivo fondamentale dello sviluppatore di Weave SDK è il miglioramento e lo sviluppo di nuove API e funzionalità dell'SDK Weave e, in molti casi, il supporto di deployment di API e funzionalità esistenti.

Laddove 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 di API e funzionalità esistenti.

Ad esempio, supponiamo che un profilo Weave, Mercury, esista attualmente nella seguente gerarchia degli spazi dei nomi non gestiti:

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 è il modulo "ombrello" intestazione. La maggior parte degli integratori include semplicemente il modulo "ombrello" come mostrato:

#include 

Tuttavia, lo sviluppatore di Mercury ha 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'utilizzo degli spazi dei nomi gestiti può aiutare a raggiungere questo obiettivo senza interrompere i deployment esistenti.

Sposta spazio dei nomi esistente in corrente

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

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

Tieni presente che, oltre a spostare i file, l'intestazione include protezioni per i file spostati che devono essere rinominati, aggiungendo potenzialmente "_CURRENT", dato che i nuovi file con lo stesso nome verranno creati al loro posto di seguito.

Una volta spostato il codice, il passaggio successivo è gestire lo spazio dei nomi con la designazione appropriata, ovvero "Current". Innanzitutto, crea un'intestazione che definisca lo spazio dei nomi gestito, come "Current/MercuryManagedNamespace.hpp". È preferibile creare un'intestazione di questo tipo rispetto alla ripetizione e alla duplicazione dei 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 <Weave/Support/ManagedNamespace.hpp>

#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 del modulo nelle intestazioni esistenti. Ad esempio:

#include 

#include 

Crea intestazioni di compatibilità

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

Per risolvere questo problema, è necessario creare intestazioni dei wrapper di compatibilità con nomi corrispondenti a quelli appena spostati.

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

Se solo uno spazio dei nomi gestito designato come Current viene creato senza creare uno spazio dei nomi gestito denominato Development- o Next che lo accompagna, i contenuti di questi file possono essere costituiti semplicemente da un'intestazione include guard e un'istruzione include che specifichi l'intestazione appena spostata con lo stesso nome:

#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 per Sviluppo o Next per consentire 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. Anche in questo caso, è preferibile ripetere e duplicare questi contenuti in ciascun 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 <Weave/Support/ManagedNamespace.hpp>

#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, come desiderato, viene impostata per impostazione predefinita la designazione dello spazio dei nomi gestito su "Attuale" se non è stata definita alcuna configurazione.

Con questa intestazione attiva, le intestazioni dei wrapper di compatibilità possono essere modificate in modo da contenere:

#include 

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

o qualsiasi altra cosa sia appropriata per il caso d'uso di gestione dello spazio dei nomi in questione.

Crea contenuti di sviluppo

A questo punto, l'infrastruttura è pronta per iniziare a creare 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 <Weave/Support/ManagedNamespace.hpp>

#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

Ovviamente, se un modulo è molto più semplice dell'esempio qui presentato e non ha molte classi, fonti, file o intestazioni, tutto può essere eseguito nello stesso file di intestazione senza spostare i file e creare più intestazioni di compatibilità e configurazione autonome. Tuttavia, con questo esempio complesso, dovrebbe ispirare soluzioni di spazio dei nomi gestiti in uno spettro da complesso a semplice.

Utilizzo degli spazi dei nomi gestiti come integratore

Un obiettivo chiave dell'integratore di SDK Weave è includere le intestazioni API pubbliche dell'SDK Weave appropriate e integrare e sviluppare le applicazioni corrispondenti.

Come esempio pratico, supponiamo di nuovo 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 è il modulo "ombrello" intestazione.

A meno che il caso d'uso in questione non spinga esplicitamente a includere 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 seguire un avanzamento nello sviluppo delle API senza modificare continuamente le istruzioni di inclusione di un progetto man mano che queste API passano per il ciclo di vita gestito.

Seguendo questa strategia, i deployment possono quindi eseguire il retargeting del proprio codice a una designazione dello spazio dei nomi gestito diversa, 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 oppure nell'intestazione di una configurazione o di un prefisso:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

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

#include 

Quando e se la designazione dello spazio dei nomi gestito cambia per le API target, ad esempio da Current a Legacy, è sufficiente eseguire il retargeting modificando la definizione del preprocessore:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy