Zarządzane przestrzenie nazw

Podsumowanie

Wprowadzenie

Zarządzane przestrzenie nazw są używane w pakiecie SDK Weave zarówno w celu zapewnienia deweloperom i integratorom pakietu Weave SDK reklamowanych wskazówek i tekstu dotyczącego wyznaczania konkretnych zestawów interfejsów API w pakiecie SDK, co pozwala im zaplanować i przewidywać ścieżkę migracji między wersjami pakietu Weave SDK oraz potencjalnie zarządzać wieloma równoczesnymi interfejsami API Weave dla danego modułu.

Oznaczenie

Zarządzanymi przestrzeniami nazw można zarządzać na 1 z 4 sposobów:

Programowanie

Każda przestrzeń nazw zarządzana przez programistów i integratorów informuje deweloperów i integratorów, że zawarte w nich interfejsy API są obecnie w fazie rozwoju, mogą ulec zmianie i nie są oficjalnie obsługiwane. Zwykle odradzamy korzystanie z tych interfejsów API integratorom, chyba że zostaną do tego specjalnie poproszeni.

Dalej

Każda przestrzeń nazw zarządzana zgodnie z oznaczeniem „Następny” informuje deweloperów i integratorów, że zawarte w nich interfejsy API (chociaż zostały w nich w dużej mierze ukończone) mogą jeszcze ulec zmianie i mogą być obsługiwane na potrzeby wczesnej oceny. Wyznaczone interfejsy API stanowią kolejny front awansowy w interfejsie Weave SDK API i w najbliższej przyszłości staną się aktualnymi, domyślnymi interfejsami API w głównym cyklu przekazywania informacji.

Zgodność wsteczna, zarówno z perspektywy interfejsu API, jak i protokołów bezprzewodowych, może istnieć, ale nie jest gwarantowana w odpowiednich interfejsach API.

Oznaczenie „Next” w ramach zarządzanej przestrzeni nazw skutecznie dostarcza deweloperom i integratorom danych o kierunku rozwoju pakietu Weave SDK, wskazując, jaki będzie aktualny, domyślny interfejs API w przyszłej wersji.

Oznaczenie „Następna zarządzana przestrzeń nazw” jest opcjonalne, dzięki czemu zarządzana przestrzeń nazw może przejść przez cykl życia bez korzystania z niego (patrz Cykl życia zarządzanej przestrzeni nazw).

Bieżące

Każda przestrzeń nazw zarządzana bieżącym oznaczeniem lub dowolną niezarządzaną przestrzenią nazw (np. bez oznaczenia zarządzanej przestrzeni nazw) reprezentuje aktualny, domyślny, oficjalny obsługiwany interfejs API dla tej części lub modułu pakietu Weave SDK. Chociaż mogą być jeszcze wprowadzane zmiany do takich interfejsów API, zmiany będą w dużej mierze stopniowe i wprowadzane w zgodność wsteczną – zarówno w przypadku interfejsów API, jak i bezprzewodowo.

Oznaczenie bieżącej zarządzanej przestrzeni nazw jest opcjonalne, dlatego zarządzana przestrzeń nazw może przejść przez cykl życia bez korzystania z niego (patrz Cykl życia zarządzanej przestrzeni nazw). W rzeczywistości każda niezarządzana przestrzeń nazw jest domyślnie ustawiona jako aktualna.

Starsza

Każda przestrzeń nazw zarządzana ze starszą wersją informuje deweloperów i integratorów, że zawarte w nich interfejsy API zostały wycofane i zastąpione nowym, aktualnym interfejsem API. Reprezentują one interfejs API dawniej znany jako bieżący.

Tak oznaczone interfejsy API znikną w następnej głównej wersji pakietu Weave SDK. W związku z tym deweloperzy i integratorzy powinni ułożyć plany migracji z innych interfejsów API, jeśli chcą zachować czołówkę w wersjach pakietu Weave SDK.

Cykl życia zarządzanej przestrzeni nazw

Poniższy rysunek przedstawia cykl życia zarządzanej przestrzeni nazw po przejściu z wersji deweloperskiej na wersję deweloperską i potencjalnie do starszej:

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

Jeśli jest używany, cykl życia zarządzanej przestrzeni nazw zaczyna się od oznaczenia Programowanie.

Gdy programowanie zostanie ukończone, a kod będzie gotowy do oceny i integracji, oznaczenie zostanie przeniesione na Dalej lub Bieżący. Ewentualnie można całkowicie usunąć to oznaczenie i nie używać zarządzanej przestrzeni nazw, co w efekcie powoduje, że oznaczenie jest domyślnie aktualne.

Jeśli kod ma być używany obok obecnego kodu, ale nie ma jeszcze zastąpić, oznaczenie powinno zostać przeniesione do następnego. Jeśli kod ma zastąpić bieżący kod, oznaczenie powinno zostać przeniesione do bieżącego.

Użycie znacznika Next oznacza, że po przejściu przez żądaną liczbę cykli publikowania i oceny kod oznaczenie zostanie przeniesione do ustawienia „Aktualne” lub też w ogóle może zostać usunięte.

Aktualne oznaczenie jest stosowane, jeśli kod ma zostać zastąpiony nowym kodem, ale nadal trzeba go zachowywać przez określoną liczbę cykli wersji, oznaczenie zostanie przeniesione do starszej wersji.

Starsze wersje kodu są ostatecznie usuwane z pakietu Weave SDK.

Korzystanie z zarządzanych przestrzeni nazw

Użytkownicy Weave SDK mogą wchodzić w interakcje z zarządzanymi przestrzeniami nazw jako deweloperzy, rozszerzać i utrzymywać istniejący kod, albo jako integrator, integrując Weave z własną aplikacją, platformą i kodem systemu. W 2 sekcjach znajdziesz szczegółowe zalecenia dotyczące korzystania z zarządzanych przestrzeni nazw Weave z tych dwóch perspektyw.

Używanie zarządzanych przestrzeni nazw jako programista

Głównym celem dewelopera Weave SDK jest ulepszanie i rozwijanie nowych interfejsów API i funkcji Weave SDK. Jednocześnie w wielu przypadkach zapewnia też obsługę dotychczasowych wdrożeń interfejsów API i funkcji.

Jeśli nie można zrealizować obu tych obszarów w sposób zgodny wstecznie w ramach tego samego interfejsu API, zarządzane przestrzenie nazw zapewniają mechanizm równoległego zarządzania tymi interfejsami API w sposób, który nie zakłóca istniejących wdrożeń interfejsów API i funkcji.

W ramach działającego przykładu załóżmy, że profil Weave o nazwie Mercury znajduje się obecnie w poniższej hierarchii niezarządzanej przestrzeni nazw:

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

// ...

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

oraz następujące nagłówki publiczne:

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

gdzie Mercury.hpp to moduł „parasol”. nagłówek. Większość integratorów używa po prostu modułu „parasol” taki nagłówek:

#include

Jednak firma stworzona przez firmę Mercury osiągnęła punkt, w którym konieczne jest opracowanie nowej generacji interfejsów API, a potencjalnie także protokołu Over-The-Wre, który nie byłby zgodny wstecznie z istniejącymi wdrożeniami. Użycie zarządzanych przestrzeni nazw może pomóc w osiągnięciu tego celu bez uszkodzenia istniejących wdrożeń.

Przenieś istniejącą przestrzeń nazw do bieżącej

Chcemy w dalszym ciągu obsługiwać obecną wersję interfejsu API i funkcje istniejących integracji, dlatego pierwszym zadaniem jest przeniesienie obecnego kodu:

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

Pamiętaj, że oprócz przeniesienia plików nagłówek zawiera zabezpieczenia przeniesionych plików należy też zmienić, dodając do nich etykietę „_CURRENT”, ponieważ poniżej będą tworzone nowe pliki o podobnych nazwach.

Po przeniesieniu kodu następnym krokiem jest zarządzanie przestrzenią nazw z użyciem odpowiedniego oznaczenia – „Current” (Aktualnie). Najpierw utwórz nagłówek definiujący zarządzaną przestrzeń nazw, w postaci „Current/MercuryManagedNamespace.hpp”. Takiego nagłówka lepiej jest utworzyć niż powtarzać i powielać tę treść w każdym pliku nagłówka, gdy jest ich wiele.

% 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

Następnie dołącz ten nagłówek przed innymi dyrektywami „include” związanymi z modułem w istniejących nagłówkach. Na przykład:

#include 

#include

Utwórz nagłówki zgodności

Przeniesienie istniejących nagłówków do nowej lokalizacji i zarządzanie tylko ich przestrzenią nazw nie wystarcza jednak do zapewnienia prawidłowego funkcjonowania istniejących wdrożeń, ponieważ wszystkie korzystają z dyrektyw „include” określających nagłówki przeniesione powyżej.

Aby rozwiązać ten problem, należy utworzyć nagłówki kodu zgodności z nazwami pasującymi do właśnie przeniesionego pliku.

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

Jeśli tworzona jest tylko zarządzana przestrzeń nazw wyznaczona na bieżącym etapie bez utworzenia zarządzanej przestrzeni nazw dla programowania lub następnej, zawartość tych plików może się składać z elementu nagłówka „include” i dyrektywy „include” określającej nowo przeniesiony nagłówek o tej samej nazwie:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Jeśli jednak tworzona jest również zarządzana przestrzeń nazw dla programistów lub na potrzeby kolejnego etapu deweloperskiego, konieczne jest wykonanie nieco bardziej złożonych działań.

Tak jak wcześniej, tworzony jest nagłówek konfiguracji zarządzanej przestrzeni nazw, tutaj jako MercuryManagedNamespace.hpp. Również w tym przypadku lepszym rozwiązaniem jest powtarzanie i duplikowanie tej treści w każdym pliku nagłówka, gdy istnieje wiele plików nagłówka.

% 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

Zwróć uwagę, że zgodnie z potrzebami jest to domyślne oznaczenie zarządzanej przestrzeni nazw „Bieżące” jeśli nie zdefiniowano żadnej konfiguracji.

Po wstawieniu tego nagłówka można edytować nagłówki kodu zgodności, aby zawierały:

#include 

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

lub innego typu, który pasuje do danego zastosowania zarządzania przestrzenią nazw.

Twórz materiały rozwojowe

Na tym etapie infrastruktura jest gotowa do tworzenia nowych funkcji i interfejsów API obok istniejących.

% 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

Oczywiście, jeśli moduł jest znacznie prostszy niż ten przykład i nie ma wielu klas, źródła, plików i nagłówków, można to zrobić w tym samym pliku nagłówka bez przenoszenia plików i tworzenia wielu samodzielnych nagłówków konfiguracji i zgodności. Jednak w przypadku tego złożonego przykładu powinien on stanowić inspirację dla rozwiązań z zakresu zarządzanej przestrzeni nazw o szerokim zakresie – od złożonego po proste.

Używanie zarządzanych przestrzeni nazw jako integratora

Integrator pakietu Weave SDK obejmuje odpowiednie nagłówki publicznych interfejsów API Weave SDK oraz integrowanie i tworzenie w nich aplikacji.

W ramach działającego przykładu ponownie załóżmy, że profil Weave o nazwie Mercury ma zarządzane przestrzenie nazw oznaczone jako Next-, Current- i Legacy, których nagłówki publiczne mają taką strukturę:

  • 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

gdzie Mercury.hpp to moduł „parasol”. nagłówek.

O ile dany przypadek użycia nie wynika wprost z zastosowania modułu zarządzanego przestrzenią nazw w Weave, na przykład:

#include

najlepiej odwoływać się do publicznych nagłówków modułu Weave, kierując się ich niezarządzanymi ścieżkami domyślnymi (np. Weave/Profiles/Mercury/Mercury.hpp). Dzięki temu można śledzić postępy w pracy nad interfejsami API bez ciągłego zmieniania dyrektyw „włącz” w projekcie, gdy te interfejsy API przechodzą przez zarządzany cykl życia.

Dzięki tej strategii wdrożenia mogą ponownie kierować swój kod na inne oznaczenie zarządzanej przestrzeni nazw, na przykład bieżące oznaczenie, określając żądaną konfigurację w procesorze C/C++. Można to zrobić w wierszu poleceń, w kodzie źródłowym, w konfiguracji lub nagłówku prefiksu:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

i użyj niezarządzanej / niezakwalifikowanej ścieżki dołączania:

#include

Gdy i jeśli oznaczenie zarządzanej przestrzeni nazw zmieni się dla docelowych interfejsów API, na przykład z obecnego na starszą wersję, po prostu zmień definicję kierowania na procesor:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy