Không gian tên được quản lý

Tóm tắt

Giới thiệu

Các không gian tên được quản lý được sử dụng trong SDK Weave để cung cấp cho cả nhà phát triển cũng như nhà tích hợp SDK Weave với hướng dẫn và văn bản phụ được quảng cáo về việc chỉ định các nhóm API cụ thể trong SDK để họ có thể lập kế hoạch và dự đoán đường dẫn di chuyển trên các bản phát hành Weave SDK và có thể quản lý đồng thời nhiều API Weave cho một mô-đun nhất định.

Ký hiệu

Bạn có thể quản lý không gian tên được quản lý theo một trong bốn cách chỉ định sau:

Quá trình phát triển

Mọi vùng chứa tên được quản lý bằng chỉ định Phát triển đều là dấu hiệu cho các nhà phát triển và nhà tích hợp biết rằng các API chứa trong đó đang trong quá trình phát triển, có thể thay đổi và không được hỗ trợ chính thức. Các nhà tích hợp thường không nên sử dụng các API này trừ phi được chỉ dẫn cụ thể để làm vậy.

Tiếp theo

Mọi không gian tên được quản lý bằng cách chỉ định Next là một dấu hiệu cho các nhà phát triển và nhà tích hợp biết rằng những API này trong đó (dù phần lớn đã hoàn tất quá trình phát triển đang hoạt động) vẫn có thể thay đổi và được hỗ trợ cho mục đích đánh giá sớm. Các API được chỉ định như vậy đại diện cho mặt trận phát triển tiếp theo trong API Weave SDK và sẽ trở thành API mặc định hiện tại trong một chu kỳ giải quyết lớn trong tương lai gần.

Khả năng tương thích ngược, cả từ góc độ API và giao thức truyền qua mạng, có thể tồn tại nhưng không được đảm bảo trong các API được chỉ định như vậy.

Việc chỉ định không gian tên được quản lý Next một cách hiệu quả giúp các nhà phát triển và nhà tích hợp nắm được vị trí mà SDK Weave sẽ phát triển bằng cách gợi ý cái sẽ trở thành API mặc định hiện tại trong bản phát hành sau này.

Bạn không bắt buộc phải chỉ định vùng chứa tên được quản lý tiếp theo để một vùng chứa tên được quản lý có thể chuyển đổi qua một vòng đời mà không cần sử dụng vùng chứa đó (xem phần Vòng đời của không gian tên được quản lý).

Hiện tại

Mọi vùng chứa tên được quản lý bằng chỉ định Hiện tại hoặc bất kỳ vùng chứa tên không được quản lý nào (tức là thiếu chỉ định vùng chứa tên được quản lý) đại diện cho API hiện tại, mặc định, được hỗ trợ chính thức cho phần hoặc mô-đun đó của Weave SDK. Mặc dù các API này có thể vẫn đang được cải tiến, nhưng bạn nên duy trì thay đổi phần lớn là tăng khả năng tương thích ngược và API.

Bạn không bắt buộc phải chỉ định vùng chứa tên được quản lý hiện tại để một vùng chứa tên được quản lý có thể chuyển đổi qua một vòng đời mà không cần sử dụng vùng chứa đó (xem phần Vòng đời của vùng chứa tên được quản lý). Trên thực tế, mọi không gian tên không được quản lý đều hoàn toàn là Hiện tại.

Cũ

Bất kỳ không gian tên nào được quản lý theo cách chỉ định Cũ đều là dấu hiệu cho các nhà phát triển và nhà tích hợp biết rằng các API trong đó đã ngừng hoạt động và được thay thế bằng một API mới hiện tại. Các API này đại diện cho API trước đây.

Các API được chỉ định như vậy sẽ biến mất hoàn toàn trong bản phát hành SDK Weave chính tiếp theo; do đó, các nhà phát triển và nhà tích hợp nên lập kế hoạch di chuyển khỏi các API này nếu họ có ý định duy trì phiên bản hàng đầu của các bản phát hành SDK Weave.

Vòng đời của không gian tên được quản lý

Hình dưới đây minh hoạ vòng đời của một không gian tên được quản lý khi không gian tên này chuyển đổi từ Phát triển và có thể là Cũ:

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

Nếu bạn sử dụng không gian tên được quản lý, vòng đời của không gian tên được quản lý sẽ bắt đầu bằng chỉ định Phát triển.

Khi quá trình phát triển hoàn tất và mã đã sẵn sàng để đánh giá và tích hợp, chế độ chỉ định sẽ di chuyển sang Tiếp theo hoặc Hiện tại. Ngoài ra, thông tin chỉ định đó có thể bị loại bỏ hoàn toàn và vùng chứa tên được quản lý không còn được sử dụng, nhờ đó, việc chỉ định đó hoàn toàn là Hiện tại.

Nếu mã này phải hoạt động song song nhưng chưa thay thế cho mã hiện tại, thì hoạt động chỉ định sẽ di chuyển sang Tiếp theo. Nếu mã này thay thế mã hiện tại, thì chỉ định sẽ chuyển sang Hiện tại.

Khi sử dụng chỉ định Next, sau khi mã đã trải qua số chu kỳ phát hành và đánh giá mong muốn, chỉ định sẽ chuyển sang Hiện tại hoặc một lần nữa, chỉ định có thể bị huỷ hoàn toàn.

Sử dụng chỉ định Hiện tại, nếu mã sẽ được thay thế bằng mã mới nhưng vẫn cần được duy trì trong một số chu kỳ phát hành, thì chỉ định sẽ di chuyển sang Cũ.

Theo chỉ định cũ, mã cuối cùng sẽ bị xoá hoàn toàn khỏi SDK Weave.

Sử dụng không gian tên được quản lý

Người dùng Weave SDK có thể tương tác với các không gian tên được quản lý với tư cách là nhà phát triển, mở rộng và duy trì mã hiện có hoặc với tư cách là nhà tích hợp, tích hợp Weave vào ứng dụng, nền tảng và mã hệ thống của riêng họ. Các đề xuất sau đây trình bày chi tiết cách xử lý không gian tên được quản lý của Weave theo hai góc nhìn đó.

Sử dụng không gian tên được quản lý với vai trò là Nhà phát triển

Trọng tâm chính của nhà phát triển Weave SDK là cải thiện và phát triển các API cũng như chức năng của Weave SDK mới, đồng thời hỗ trợ các triển khai chức năng và API hiện có trong nhiều trường hợp.

Nếu không thể đáp ứng cả hai khía cạnh trọng tâm này theo cách tương thích ngược trong cùng một API, không gian tên được quản lý sẽ cung cấp cơ chế quản lý song song các API này theo cách không làm gián đoạn việc triển khai API và chức năng hiện có.

Ví dụ: giả sử một hồ sơ Weave, Mercury, hiện đang tồn tại dưới hệ phân cấp không gian tên không được quản lý như sau:

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

// ...

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

và các tiêu đề công khai sau:

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

trong đó Mercury.HPp là mô-đun "ô" . Hầu hết các nhà tích hợp chỉ bao gồm "ô" mô-đun như sau:

#include

Tuy nhiên, công ty phát triển Mercury hiện đã đạt đến điểm cần phải phát triển một thế hệ API mới và có khả năng là giao thức truyền qua mạng không dây không tương thích ngược với các tính năng triển khai hiện có. Việc sử dụng không gian tên được quản lý có thể giúp thực hiện việc này mà không phá vỡ các quy trình triển khai hiện có này.

Di chuyển không gian tên hiện tại sang hiện tại

Với mục tiêu tiếp tục hỗ trợ bản phát hành API và chức năng hiện tại cho các công cụ tích hợp đã triển khai hiện có, nhiệm vụ đầu tiên là di chuyển mã hiện tại:

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

Lưu ý: ngoài việc di chuyển tệp, bạn cũng nên đổi tên tiêu đề bao gồm các biện pháp bảo vệ cho tệp đã di chuyển, có thể trang trí chúng bằng '_CURRENT', vì các tệp mới có tên giống sẽ được tạo ở vị trí bên dưới.

Sau khi mã được di chuyển, bước tiếp theo là quản lý không gian tên bằng cách chỉ định thích hợp ở đây là "Hiện tại". Trước tiên, hãy tạo tiêu đề xác định không gian tên được quản lý, chẳng hạn như "Current/MercuryManagedNamespace.HPp". Việc tạo tiêu đề như vậy sẽ ưu tiên hơn việc lặp lại và sao chép nội dung này trong mỗi tệp tiêu đề khi có nhiều tệp tiêu đề.

% 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

Tiếp theo, đưa tiêu đề này vào trước các lệnh bao gồm dành riêng cho mô-đun khác trong các tiêu đề hiện tại. Ví dụ:

#include 

#include

Tạo tiêu đề tương thích

Tuy nhiên, việc di chuyển các tiêu đề hiện có đến vị trí mới và chỉ quản lý không gian tên của các tiêu đề đó là không đủ để đảm bảo rằng các hoạt động triển khai hiện có sẽ hoạt động mà không có thay đổi nào vì tất cả đều sử dụng lệnh include được chỉ định tiêu đề vừa được di chuyển ở trên.

Để giải quyết vấn đề này, bạn phải tạo tiêu đề trình bao bọc khả năng tương thích có tên khớp với các tiêu đề vừa được di chuyển.

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

Nếu chỉ có một vùng chứa tên được quản lý được chỉ định hiện tại đang được tạo mà không tạo một vùng chứa tên được quản lý được chỉ định là Phát triển hoặc Tiếp theo đi kèm, thì nội dung của các tệp này có thể chỉ cần bao gồm một tiêu đề bao gồm bảo vệ và một lệnh bao gồm chỉ định tiêu đề mới được di chuyển của cùng một tên:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Tuy nhiên, nếu một vùng chứa tên được quản lý được chỉ định là Phát triển hoặc Tiếp theo cũng được tạo để hỗ trợ quá trình phát triển mới, không tương thích, thì bạn sẽ phải thực hiện một việc phức tạp hơn một chút.

Như trước đó, tiêu đề cho cấu hình không gian tên được quản lý được tạo, ở đây là MercuryManagedNamespace.HPp. Xin nhắc lại, bạn nên lặp lại và sao chép nội dung này trong từng tệp tiêu đề khi có nhiều tệp tiêu đề.

% 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

Lưu ý rằng, như mong muốn, việc chỉ định không gian tên được quản lý sẽ là "Hiện tại" theo mặc định nếu chưa xác định cấu hình.

Với tiêu đề này, giờ đây, bạn có thể chỉnh sửa tiêu đề trình bao bọc khả năng tương thích để chứa:

#include 

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

hoặc bất kỳ nội dung nào phù hợp với trường hợp sử dụng quản lý không gian tên đang áp dụng.

Tạo nội dung phát triển

Tại thời điểm này, cơ sở hạ tầng đã sẵn sàng để bắt đầu xây dựng chức năng và API mới bên cạnh các chức năng và API hiện có.

% 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

Tất nhiên, nếu một mô-đun đơn giản hơn nhiều so với ví dụ trình bày ở đây và không có nhiều lớp, nguồn, tệp hoặc tiêu đề, thì bạn có thể thực hiện tất cả trong cùng một tệp tiêu đề mà không cần di chuyển các tệp và tạo nhiều cấu hình độc lập và tiêu đề tương thích. Tuy nhiên, với ví dụ phức tạp này, hệ thống sẽ gợi ý cho bạn các giải pháp cho không gian tên được quản lý theo nhiều khía cạnh từ phức tạp đến đơn giản.

Sử dụng không gian tên được quản lý làm đơn vị tích hợp

Trọng tâm chính của nhà tích hợp SDK Weave là bao gồm các tiêu đề API công khai thích hợp của Weave SDK cũng như tích hợp và phát triển các ứng dụng dựa trên các tiêu đề đó.

Ví dụ đang hoạt động: Một lần nữa giả định một hồ sơ Weave là Mercury. Hồ sơ này có các không gian tên được quản lý được chỉ định là Tiếp theo, Hiện tại và Kế thừa có tiêu đề công khai có cấu trúc như sau:

  • 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

trong đó Mercury.HPp là mô-đun "ô" .

Trừ phi trường hợp sử dụng đang sử dụng thúc đẩy việc thêm mô-đun được quản lý không gian tên trong Weave một cách rõ ràng, ví dụ:

#include

tốt nhất là bạn nên tham chiếu các tiêu đề công khai của mô-đun Weave bằng các đường dẫn mặc định, không được quản lý (ví dụ: Weave/Profiles/Mercury/Mercury.HPp). Cách làm này giúp bạn theo dõi tiến trình phát triển API mà không cần liên tục thay đổi các lệnh bao gồm của dự án vì các API đó trải qua vòng đời được quản lý.

Theo chiến lược này, các hoạt động triển khai có thể nhắm mục tiêu lại mã tại chỉ định không gian tên được quản lý khác, chẳng hạn như chỉ định Hiện tại, bằng cách chỉ định cấu hình mong muốn trong bộ tiền xử lý C/C++. Bạn có thể thực hiện việc này trên dòng lệnh, trong mã nguồn hoặc trong một tiêu đề cấu hình hoặc tiền tố:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

và sử dụng đường dẫn không được quản lý / không đủ điều kiện, bao gồm:

#include

Khi và nếu, thông tin chỉ định không gian tên được quản lý thay đổi đối với các API được nhắm mục tiêu, chẳng hạn như từ Hiện tại thành Cũ, thì bạn chỉ cần nhắm mục tiêu lại bằng cách điều chỉnh định nghĩa của bộ tiền xử lý:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy