דף זה תורגם על ידי Cloud Translation API.

מרחבי שמות מנוהלים

סיכום

מבוא

מרחבי שמות מנוהלים משמשים ב-Weave SDK כדי לספק למפתחים ולמטמיעים של Weave SDK, לצד הנחיות ותת-טקסט בנוגע לסיווג של קבוצות API מסוימות ב-SDK, כדי שיוכלו לתכנן ולחזות את נתיב ההעברה שלהן בגרסאות Weave SDK, ואולי גם לנהל כמה ממשקי API של Weave בו-זמנית למודול נתון.

ייעוד

אפשר לנהל מרחבי שמות מנוהלים כאחד מארבעה סיווגים:

פיתוח

כל מרחב שמות שמנוהל באמצעות סיווג הפיתוח הוא אינדיקציה למפתחים ולמטמיעים שממשקי ה-API שכלולים בהם נמצאים בפיתוח פעיל ועשויים להשתנות והם לא נתמכים באופן רשמי. באופן כללי, מבצעי שילוב אינם מעוניינים להשתמש בממשקי ה-API האלה, אלא אם הם הופנו לכך באופן ספציפי.

כל מרחב שמות שמנוהל באמצעות הסיווג 'הבא' הוא אינדיקציה למפתחים ולמטמיעים שממשקי ה-API שכלולים בהם, למרות שהפיתוח שלהם הושלם ברובם, עדיין עשויים להשתנות ונתמכים למטרות הערכה מוקדמת. ממשקי ה-API האלה מייצגים את החזית האבולוציה הבאה ב-Weave SDK API, ויהפכו לממשקי ה-API הנוכחיים שמוגדרים כברירת מחדל במחזורים משמעותיים, באופן מיידי ובעתיד הקרוב.

תאימות לאחור, הן מה-API וגם מההיבט של פרוטוקול 'בחיבור אלחוטי', עשויה להיות קיימת, אבל לא מובטחת בממשקי API שייעדו כך.

הסיווג 'מרחב השמות המנוהל הבא' מאפשר למפתחים ולמטמיעים לראות לאן מוביל את Weave SDK – הוא מרמז על מה שיהפוך לממשק ה-API הנוכחי שמוגדר כברירת מחדל בגרסה עתידית.

הסיווג של מרחב השמות המנוהל הבא הוא אופציונלי, כך שמרחב שמות מנוהל עשוי לעבור במחזור חיים בלי להשתמש בו (ראו מחזור החיים של מרחב שמות מנוהל).

היחס הנוכחי

כל מרחב שמות שמנוהל באמצעות הסיווג 'נוכחי' או כל מרחב שמות לא מנוהל (כלומר, ללא סיווג מנוהל של מרחב שמות) מייצג את ה-API הרשמי הנתמך הנוכחי, שמוגדר כברירת מחדל, לחלק או למודול הזה של Weave SDK. אומנם עדיין עשויים לחול שיפורים מתמשכים בממשקי ה-API האלה, אבל השינויים יהיו בעיקר בתאימות מצטברת לאחור, צריך לתחזק גם את ה-API וגם באופן אלחוטי.

הסיווג של מרחב השמות המנוהל הנוכחי הוא אופציונלי, כך שמרחב שמות מנוהל עשוי לעבור במחזור חיים בלי להשתמש בו (מידע נוסף זמין במחזור החיים של מרחב שמות מנוהל). למעשה, כל מרחב שמות לא מנוהל הוא 'נוכחי' באופן מרומז.

הדור הקודם

כל מרחב שמות שמנוהל באמצעות הסיווג 'מדור קודם' הוא אינדיקציה למפתחים ולמטמיעים שממשקי ה-API שכלולים בהם הוצאו משימוש ומחליפים אותם בממשק API חדש ונוכחי. ממשקי ה-API האלה מייצגים את מה שהיה בעבר ה-API הנוכחי.

ממשקי API שהוגדרו כך ייעלמו לגמרי במהדורה הראשית הבאה של Weave SDK. כתוצאה מכך, מפתחים ומטמיעים צריכים לתכנן את המעבר משימוש בממשקי ה-API האלה, אם הם מתכוונים להישאר עם הגרסה המתקדמת של גרסאות Weave SDK.

מחזור החיים של מרחב שמות מנוהל

האיור הבא ממחיש את מחזור החיים של מרחב שמות מנוהל בזמן המעבר מ'פיתוח', באופן פוטנציאלי, גם למודל Legacy:

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

אם משתמשים בו, מחזור החיים של מרחב השמות המנוהל מתחיל בסיווג 'פיתוח'.

כשהפיתוח הושלם והקוד מוכן להערכה ולהטמעה, הסיווג עובר ל'הבא' או ל'נוכחי'. לחלופין, ייתכן שהסיווג יבוטל לגמרי ויפסיקו להשתמש במרחב השמות המנוהל, כך שהסיווג יהפוך בפועל ל'נוכחי' באופן מרומז.

אם הקוד פועל לצד הקוד הנוכחי ועדיין לא מחליף את הקוד הנוכחי, הסיווג אמור לעבור ל'הבא'. אם הקוד נועד להחליף את הקוד הנוכחי, הסיווג אמור לעבור ל'נוכחי'.

בסיווג Next, לאחר שהקוד עבר את המספר הרצוי של מחזורי הפצה והערכה, הסיווג עובר ל'נוכחי' או שוב, ייתכן שהסיווג יבוטל לחלוטין.

בעזרת הסיווג הנוכחי, אם קוד חדש מחליף את הקוד אבל עדיין צריך לתחזק אותו במשך מספר מחזורי גרסאות, הסיווג עובר לגרסה הקודמת.

מהסיווג 'מדור קודם', הקוד מוסר לגמרי מ-Weave SDK.

שימוש במרחבי שמות מנוהלים

משתמשי Weave SDK יכולים ליצור אינטראקציה עם מרחבי שמות מנוהלים בתור מפתחים, להרחיב ולתחזק קוד קיים, או כמשלבים, לשלב את Weave באפליקציה, בפלטפורמה ובקוד המערכת שלהם. בשני הסעיפים הבאים מפורטות המלצות להתמודדות עם מרחבי שמות מנוהלים של Weave משתי נקודות המבט האלה.

שימוש במרחבי שמות מנוהלים כמפתח

המטרה העיקרית של מפתחי Weave SDK היא שיפור ופיתוח של פונקציונליות וממשקי API חדשים של Weave SDK, ובמקרים רבים במקביל, תמיכה בפריסות קיימות של ממשקי API ופונקציות.

כאשר לא ניתן לספק מענה לשני אזורי המיקוד האלה באמצעות תאימות לאחור במסגרת אותו API, מרחבי שמות מנוהלים מספקים מנגנון לניהול ממשקי ה-API האלה במקביל, באופן שלא מפריע לפריסות הקיימות של ה-API ושל הפונקציונליות.

כדוגמה פעילה, נניח שפרופיל Weave, כספית, שקיים כרגע בהיררכיה הבאה של מרחב שמות, שאינה מנוהלת:

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

// ...

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

והכותרות הציבוריות הבאות:

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

כאשר Mercury.hpp הוא המודול "מטריה" הכותרת. רוב המטמיעים פשוט כוללים את המודול "מטריה" כותרת כפי שמוצג:

#include

עם זאת, הפיתוח של Mercury הגיע לנקודה שבה צריך לפתח את הדור הבא של ממשקי ה-API, ואולי גם את הפרוטוקול ברשת הסלולרית שלא תואם לאחור לפריסות קיימות. שימוש במרחבי שמות מנוהלים יכול לעזור לעשות זאת בלי לפגוע בפריסות הקיימות.

העברת מרחב השמות הקיים לנוכחי

כדי להמשיך לתמוך בגרסה הנוכחית של ה-API ובפונקציונליות של שילובים קיימים שנפרסו, המשימה הראשונה היא להעביר את הקוד הנוכחי:

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

הערה: בנוסף להעברת הקבצים, צריך לשנות גם את השם של הכותרת שכוללת שומרים עבור הקבצים שהועברו, וייתכן לקשט אותם ב-' _CURRENT' כי קבצים חדשים בעלי שם דומה ייווצרו במקום שלהם בהמשך.

השלב הבא הוא ניהול מרחב השמות עם הסיווג המתאים, כאן: 'Current' (נוכחי). תחילה, יוצרים כותרת שמגדירה את מרחב השמות המנוהל:Current/MercuryManagedNamespace.hpp. עדיפה יצירת כותרת כזו על ידי חזרה ושכפול של התוכן הזה בכל קובץ כותרת כשיש מספר קובצי כותרת.

% 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

לאחר מכן, כוללים בכותרות הקיימות את הכותרת הזו לפני הוראות הכללה אחרות שספציפיות למודול. לדוגמה:

#include 

#include

יצירת כותרות תאימות

אבל העברת הכותרות הקיימות למיקום חדש וניהול מרחב השמות שלהן בלבד לא מבטיחה שהפריסות הקיימות יפעלו ללא שינוי, כי כולן משתמשות בהוראות הכללה שמציינות את הכותרות שהועברו למעלה.

כדי לפתור את הבעיה, צריך ליצור כותרות wrapper של תאימות עם שמות שתואמים לשמות שהועברו.

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

אם נוצר רק מרחב שמות מנוהל ייעודי הנוכחי בלי ליצור מרחב שמות מנוהל ייעודי ל- Development או ל-Next, תוכן הקבצים יכול פשוט להכיל כותרת עם שומר והוראת הכללה שמציינת את הכותרת החדשה שהועברה באותו שם:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

עם זאת, אם יוצרים גם מרחב שמות מנוהל שמיועד לפיתוח או ל'הבא' כדי לכלול פיתוח חדש ולא תואם, צריך לבצע פעולה קצת יותר מורכבת.

כמו קודם, נוצרת כותרת לתצורת מרחב השמות המנוהל, כאן בשם MercuryManagedNamespace.hpp. שוב, עדיף לחזור על התוכן הזה ולהעתיק אותו בכל קובץ כותרת כשיש מספר קובצי כותרת.

% 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

שימו לב שברירת המחדל של ההגדרה הזו היא 'נוכחי', באופן הרצוי, הסיווג של מרחב השמות המנוהל אם לא הוגדרו הגדרות אישיות.

כשהכותרת הזו קיימת, אפשר עכשיו לערוך את כותרות ה-wrapper של התאימות כך שיכללו:

#include 

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

או כל פתרון שמתאים לתרחיש לדוגמה של ניהול מרחב שמות.

יצירת תוכן לפיתוח

בשלב הזה, התשתית מתחילה ליצור פונקציונליות וממשקי API חדשים לצד אלה הקיימים.

% 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

כמובן שאם המודול פשוט יותר מהדוגמה שמוצגת כאן, ואין לו מספר רב של מחלקות, מקור, קבצים או כותרות, ניתן לעשות זאת באותו קובץ כותרת בלי להזיז את הקבצים וליצור כותרות נפרדות של תצורה ותאימות. עם זאת, על סמך הדוגמה המורכבת הזו, הפתרון הזה צריך לעורר השראה לפתרונות מנוהלים של מרחב שמות על פני מגוון רחב של פתרונות, ממורכבים לפשוטים.

שימוש במרחבי שמות מנוהלים כמטמיע

המוקד העיקרי של משלב ה-SDK ב-Weave הוא כולל את כותרות ה-API הציבוריות המתאימות של Weave SDK ושילוב ופיתוח של אפליקציות מולן.

כדוגמה פעילה, נניח שוב את פרופיל Weave, Mercury, שיש לו מרחבי שמות מנוהלים שמיועדים ל-Next-, ל-Current ול-Legacy, והכותרות הציבוריות שלהם בנויות באופן הבא:

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

כאשר Mercury.hpp הוא המודול "מטריה" הכותרת.

אלא אם התרחיש לדוגמה הנדון מניע להכללה של מודול מנוהל על ידי מרחב שמות ב-Weave באופן מפורש, לדוגמה:

#include

מומלץ להפנות לכותרות ציבוריות של מודול Weave לפי נתיבי ברירת המחדל הלא מנוהלים (למשל: Weave/Profiles/Mercury/Mercury.hpp). כך ניתן לעקוב אחרי התקדמות פיתוח ה-API בלי לשנות באופן רציף את הוראות ההכללה של הפרויקט, בזמן שממשקי ה-API האלה עוברים במחזור החיים המנוהל.

בהתאם לאסטרטגיה הזאת, פריסות יכולות לטרגט מחדש את הקוד שלהן לפי סיווג מנוהל שונה למרחב שמות מנוהל, כמו הסיווג 'נוכחי', למשל, על ידי ציון ההגדרה הרצויה במעבד המקדים C/C++. אפשר לעשות זאת בשורת הפקודה, בקוד המקור, או בכותרת של מערך הגדרות אישיות או קידומת:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

ומשתמשים בנתיב הכללה לא מנוהל / לא כשיר:

#include

מתי, ואם, סיווג מרחב השמות המנוהל משתנה עבור ממשקי ה-API המטורגטים, לדוגמה מ'נוכחי' ל'מדור קודם', פשוט מבצעים טירגוט מחדש על ידי התאמת ההגדרה של המעבד המידע מראש:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy