Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

Se usó la API de Cloud Translation para traducir esta página.

Espacios de nombres administrados

Resumen

Introducción

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

Designación

Los espacios de nombres administrados se pueden administrar como una de las cuatro designaciones:

Desarrollo

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

Cualquier espacio de nombres administrado con la designación Next indica a los desarrolladores y a los integradores que las APIs incluidas en ellas, si bien completaron en gran medida el desarrollo activo, pueden estar sujetos a cambios y se admiten para fines de evaluación temprana. Las APIs designadas representan el próximo frente evolutivo en una API del SDK de Weave y se convertirán en las APIs predeterminadas actuales en un ciclo de versiones principales, desde el futuro inmediato hasta el cercano.

Puede existir retrocompatibilidad, tanto desde una perspectiva de API como de protocolo por cable, pero no está garantizada en las APIs así designadas.

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

La designación del espacio de nombres administrado Next 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).

Actual

Cualquier espacio de nombres administrado con la designación actual o cualquier espacio de nombres no administrado (es decir, que no tenga una designación de espacio de nombres administrado) representa la API actual, predeterminada y oficial admitida para esa parte o módulo del SDK de Weave. Si bien aún puede haber mejoras continuas en dichas APIs, los cambios serán en gran medida de compatibilidad incremental y retrocompatible, tanto de la API como de la conexión por cable.

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 Current de forma implícita.

Heredada

Cualquier espacio de nombres administrado con la designación de Heredado indica a los desarrolladores y a los integradores que las APIs incluidas en ellas dejaron de estar disponibles y se reemplazaron por una API nueva y actual. Estas APIs representan lo que antes era la API actual.

Las APIs así designadas desaparecerán por completo en la próxima versión importante del SDK de Weave. En consecuencia, los desarrolladores y los integradores deben establecer planes de migración fuera de estas APIs si desean 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 del desarrollo y, posiblemente, al heredado:

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

Si se emplea, el ciclo de vida del espacio de nombres administrado comienza con la designación de 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 utiliza, lo que hace que la designación se considere implícitamente actual.

Si el código es para acompañar y aún no suplanta al actual, la designación debe migrar a Next. Si el código es sustituir el código actual, la designación debería 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, nuevamente, la designación puede descartarse por completo.

Con la designación Current, si el código se reemplazará por uno nuevo, pero aún se debe mantener durante varios ciclos de lanzamiento, la designación migra a Heredado.

Desde la designación heredada, el código se quita con el tiempo por completo del SDK de Weave.

Usa espacios de nombres administrados

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

Usa espacios de nombres administrados como desarrollador

Uno de los enfoques clave del desarrollador del SDK de Weave es mejorar y desarrollar nuevas API y funcionalidad del SDK de Weave y, en muchos casos, admitir al mismo tiempo implementaciones existentes de API y funciones.

Cuando no es posible satisfacer ambas áreas de enfoque de 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 funcional, imagina un perfil de Weave, Mercury, que existe actualmente 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

en el que Mercury.hpp es el módulo "umbrella" encabezado. La mayoría de los integradores simplemente incluyen el módulo “umbrella” encabezado como se muestra a continuación:

#include

Sin embargo, el desarrollador de Mercury ha llegado a un punto en el que se necesita desarrollar una nueva generación de las APIs y, posiblemente, un protocolo por cable que no sea retrocompatible con las implementaciones existentes. El uso de espacios de nombres administrados puede ayudar a lograr esto sin afectar estas implementaciones existentes.

Mover el espacio de nombres existente a Current

Con el objetivo de continuar 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, también se debe cambiar el nombre del encabezado que incluye protecciones para los archivos movidos, lo que podría decorarlos con "_CURRENT", ya que los nuevos archivos con nombres similares se crearán en su lugar a continuación.

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

% 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

A continuación, incluye este encabezado antes de otras directivas de inclusión específicas del módulo 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 acabaron 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 designado como Current sin crear un espacio de nombres administrado designado por Development o Next para acompañarlo, el contenido de estos archivos puede consistir simplemente en una protección de inclusión de encabezado y una directiva de inclusión que especifique el encabezado recientemente 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 designado por Development o Next para adaptarse a un desarrollo nuevo e incompatible, se debe hacer algo un poco más complejo.

Al igual que antes, se crea un encabezado para la configuración del espacio de nombres administrado, aquí como MercuryManagedNamespace.hpp. Nuevamente, es preferible esto 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 <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

Ten en cuenta que, de forma predeterminada, la designación del espacio de nombres administrado es “Actual”, según lo desees. si no se definió ninguna configuración.

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

#include 

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

o 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 crear 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 <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

Por supuesto, si un módulo es mucho más simple que el ejemplo que se presenta aquí y no tiene muchas clases, fuentes, archivos o encabezados, todo esto se podría lograr en el mismo archivo de encabezado sin mover los archivos y crear varios encabezados de configuración y compatibilidad independientes. Sin embargo, con este ejemplo complejo, debería inspirar soluciones de espacios de nombres administrados a lo largo de un espectro que va desde complejo hasta simple.

Usa espacios de nombres administrados como integrador

Un enfoque clave del integrador de SDK de Weave consiste en incluir los encabezados de API públicas de SDK de Weave adecuados e integrar y desarrollar aplicaciones en función de ellos.

Como ejemplo funcional, vuelve a suponer un perfil de Weave, Mercury, que tiene espacios de nombres administrados designados como 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

en el que Mercury.hpp es el módulo "umbrella" encabezado.

A menos que el caso de uso en cuestión motive incluir explícitamente 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 y no administradas (p.ej., Weave/Profiles/Mercury/Mercury.hpp). Esto permite seguir el desarrollo de las APIs sin cambiar continuamente las directivas de inclusión de un proyecto a medida que esas APIs fluyen por el ciclo de vida administrado.

Siguiendo 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, especificando 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 un encabezado de configuración o prefijo:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

Usa la ruta de inclusión no administrada o no calificada:

#include

Cuando la designación del espacio de nombres administrado cambia para las APIs de destino (por ejemplo, de Actual a Heredada), vuelve a segmentar tus anuncios ajustando la definición del preprocesador:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy