Espacios de nombres administrados

Resumen

Introducción

Los espacios de nombres administrados se usan en el SDK de Weave para proporcionar orientación y subtexto anunciados a los desarrolladores y los integradores del SDK de Weave sobre la designación de conjuntos de APIs particulares dentro del SDK, de modo que puedan planificar y predecir su ruta de migración entre las versiones del SDK de Weave y, posiblemente, administrar múltiples APIs de Weave simultáneas para un módulo determinado.

Designación

Los espacios de nombres administrados pueden gestionarse como una de estas cuatro designaciones:

Desarrollo

Cualquier espacio de nombres administrado con la designación Desarrollo indica para los integradores y desarrolladores que las APIs incluidas en su desarrollo están en desarrollo activo, pueden estar sujetas a cambios y no son compatibles oficialmente. Por lo general, no se recomienda a los integradores usar estas APIs, a menos que se les indique específicamente que lo hagan.

Siguiente

Cualquier espacio de nombres administrado con la designación Next indica para los integradores y desarrolladores que las APIs contenidas en su interior, si bien completaron en gran medida el desarrollo activo, pueden estar sujetas a cambios y son compatibles con fines de evaluación temprana. Las APIs designadas representan el siguiente frente evolutivo en una API de SDK de Weave y se convertirán en las APIs predeterminadas actuales en un ciclo de lanzamientos importante de inmediato o cercano.

Es posible que exista retrocompatibilidad, tanto desde la perspectiva de la API como del protocolo por cable, pero no se garantiza en las APIs así designadas.

La designación de espacio de nombres administrado Next proporciona de manera efectiva a los integradores y desarrolladores una vista hacia dónde se dirige el SDK de Weave, ya que sugiere lo que se convertirá en la API predeterminada actual en una versión futura.

La designación del espacio de nombres administrado a continuación es opcional, de modo que un espacio de nombres administrado puede pasar por un ciclo de vida sin usarlo (consulta Ciclo de vida del espacio de nombres administrado).

Actual

Cualquier espacio de nombres administrado con la designación Current o cualquier espacio de nombres no administrado (es decir, sin una designación de espacio de nombres administrado) representa la API compatible oficial, predeterminada y actual, para esa parte o módulo del SDK de Weave. Aunque todavía puede haber mejoras continuas para esas APIs, los cambios serán en gran medida incrementales y retrocompatibles, tanto de la API como de la conexión inalámbrica, se deben mantener.

La designación del espacio de nombres administrado actual es opcional, de modo que un espacio de nombres administrado pueda pasar por un ciclo de vida sin usarlo (consulta Ciclo de vida del espacio de nombres administrado). De hecho, cualquier espacio de nombres no administrado es actual de manera implícita.

Heredada

Cualquier espacio de nombres administrado con la designación heredada es una indicación para los integradores y desarrolladores de que las APIs incluidas en su contenido quedaron obsoletas y se reemplazaron por una API nueva y actual. Estas APIs representan lo que antes era la API actual.

Las APIs designadas desaparecerán por completo en la próxima versión importante del SDK de Weave. En consecuencia, los integradores y desarrolladores deben establecer planes de migración lejos de estas APIs si quieren mantenerse a la vanguardia de las versiones del SDK de Weave.

Ciclo de vida del espacio de nombres administrado

En la siguiente figura, se ilustra el ciclo de vida de un espacio de nombres administrado a medida que pasa de desarrollo y, potencialmente, a heredado:

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

Si se utiliza, el ciclo de vida del espacio de nombres administrado comienza con la designación Desarrollo.

Cuando se completa el desarrollo y el código está listo para la evaluación y la integración, la designación migra a Next o Current. Como alternativa, la designación se puede descartar por completo y el espacio de nombres administrado ya no se emplea, lo que hace que la designación sea implícitamente actual.

Si el código debe existir junto con el código actual y aún no suplantar el actual, la designación debe migrar a Next. Si el código es suplantar el código actual, la designación debe migrar a Current.

Con la designación Next, una vez que el código haya superado la cantidad deseada de ciclos de lanzamiento y evaluación, la designación migra a Current o, una vez más, puede descartarse por completo.

Con la designación Current, si el código nuevo tiene que suplantarlo, pero aún necesita mantenerse durante varios ciclos de lanzamiento, la designación migra a Legacy.

A partir de la designación Legacy, el código se quita finalmente del SDK de Weave.

Usa espacios de nombres administrados

Los usuarios del SDK de Weave pueden interactuar con espacios de nombres administrados como desarrolladores, extendiendo y manteniendo el código existente, o como integrador, integrando Weave en su propia aplicación, plataforma y código de sistema. En las siguientes dos secciones, se detallan las recomendaciones para trabajar con los espacios de nombres administrados de Weave desde esas dos perspectivas.

Usa espacios de nombres administrados como desarrollador

Un enfoque clave del desarrollador del SDK de Weave es mejorar y desarrollar nuevas API y funcionalidades del SDK de Weave y, al mismo tiempo, admitir implementaciones de API y funcionalidades existentes.

Cuando no es posible satisfacer ambas áreas de enfoque de una manera retrocompatible dentro de la misma API, los espacios de nombres administrados proporcionan un mecanismo para administrar estas APIs en paralelo, de una manera que no interrumpe las implementaciones existentes de la API y la funcionalidad.

Como ejemplo de funcionamiento, imagina un perfil de Weave, Mercury, que actualmente existe bajo la siguiente jerarquía de espacio de nombres no administrada:

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

// ...

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

y los siguientes encabezados públicos:

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

donde Mercury.hpp es el encabezado "umbrella" del módulo. La mayoría de los integradores simplemente incluyen el encabezado "umbrella" del módulo, como se muestra a continuación:

#include 

Sin embargo, el desarrollador de Mercury ha llegado a un punto en el que es necesario desarrollar una nueva generación de las API y, posiblemente, el protocolo por cable que no son retrocompatibles con las implementaciones existentes. El uso de espacios de nombres administrados puede ayudar a lograr esto sin interrumpir estas implementaciones existentes.

Mover el espacio de nombres existente al actual

Con el objetivo de seguir admitiendo la versión actual de la API y la funcionalidad para las integraciones implementadas existentes, la primera tarea es mover el código actual:

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

Ten en cuenta que, además de mover los archivos, el encabezado que incluye las protecciones para los archivos que se movieron también debe cambiarse de nombre, posiblemente decorando con "_CURRENT", ya que los nuevos archivos con nombres similares se crearán en su lugar a continuación.

Una vez que se movió el código, el siguiente paso es administrar el espacio de nombres con la designación adecuada, aquí 'Current'. Primero, crea un encabezado que defina el espacio de nombres administrado, como “Current/MercuryManagedSPACE.hpp”. Es preferible crear este encabezado en lugar de repetir y duplicar este contenido en cada archivo de encabezado cuando existen varios archivos de encabezado.

% 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

A continuación, incluye este encabezado antes de otras directivas de inclusión específicas de módulos en los encabezados existentes. Por ejemplo:

#include 

#include 

Crea encabezados de compatibilidad

Sin embargo, mover los encabezados existentes a una ubicación nueva y administrar solo el espacio de nombres no es suficiente para garantizar que las implementaciones existentes funcionen sin cambios, ya que todas usan directivas de inclusión que especificaron los encabezados que se acaban de mover.

Para solucionar este problema, se deben crear encabezados de wrapper de compatibilidad con nombres que coincidan con los que se acaban de mover.

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

Si solo se crea un espacio de nombres administrado que se designa como actual sin crear un espacio de nombres administrado de desarrollo o a continuación que lo acompañe, el contenido de estos archivos puede consistir simplemente en una protección de encabezado y una directiva de inclusión que especifique el encabezado recién movido con el mismo nombre:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Sin embargo, si también se crea un espacio de nombres administrado que se designa como desarrollo o a continuación para adaptarse a un desarrollo nuevo e incompatible, se debe hacer algo un poco más complejo.

Como antes, se crea un encabezado para la configuración del espacio de nombres administrado, aquí como MercuryManagedEspacio de nombres.hpp. De nuevo, esto es preferible a repetir y duplicar este contenido en cada archivo de encabezado cuando hay varios archivos de encabezado.

% 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

Ten en cuenta que, según lo desees, la designación del espacio de nombres administrado será “Current” si no se definió ninguna configuración.

Una vez implementado este encabezado, se pueden editar los encabezados del wrapper de compatibilidad para que contengan lo siguiente:

#include 

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

o según lo que sea apropiado para el caso de uso de administración de espacios de nombres.

Crea contenido de desarrollo

En este punto, la infraestructura ya está lista para comenzar a desarrollar nuevas funcionalidades y APIs junto con las existentes.

% 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

Por supuesto, si un módulo es mucho más simple que el ejemplo que se presenta aquí y no tiene muchas clases, fuente, archivos o encabezados, esto se puede lograr en el mismo archivo de encabezado sin mover archivos ni crear varios encabezados de compatibilidad y configuración independientes. Sin embargo, con este complejo ejemplo, debería inspirar soluciones de espacio de nombres administradas en un espectro de complejo a simple.

Usa espacios de nombres administrados como integrador

Un enfoque clave del integrador del SDK de Weave es incluir los encabezados correspondientes de la API pública del SDK de Weave, así como integrar y desarrollar aplicaciones en función de ellos.

Como ejemplo de funcionamiento, vuelve a suponer un perfil de Weave, Mercury, que tiene espacios de nombres administrados designados Next-, Current- y Legacy, cuyos encabezados públicos están estructurados de la siguiente manera:

  • 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

donde Mercury.hpp es el encabezado "umbrella" del módulo.

A menos que el caso de uso en cuestión motive incluir de forma explícita un módulo administrado de espacio de nombres en Weave, por ejemplo:

#include 

es mejor hacer referencia a los encabezados públicos del módulo de Weave por sus rutas de acceso predeterminadas no administradas (p.ej., Weave/Profiles/Mercury/Mercury.hpp). Esto permite seguir un progreso del desarrollo de la API sin cambiar de forma continua las directivas de inclusión de un proyecto a medida que esas APIs fluyen por el lifecycle administrado.

Con esta estrategia, las implementaciones pueden reorientar su código a una designación de espacio de nombres administrado diferente, la designación Current, por ejemplo, mediante la especificación de la configuración deseada en el preprocesador de C/C++. Esto se puede hacer en la línea de comandos, en el código fuente o en una configuración o un encabezado de prefijo:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

y usar la ruta de acceso de inclusión no administrada o no calificada:

#include 

Cuando cambie la designación del espacio de nombres administrado para las APIs de destino (por ejemplo, de Current a Legacy) y reorientarla, solo debes ajustar la definición del preprocesador:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy