با نکات عملکرد CPU، یک بازی می تواند بر رفتار عملکرد پویا CPU برای مطابقت بهتر با نیازهای آن تأثیر بگذارد. در اکثر دستگاه‌ها، اندروید به صورت پویا سرعت ساعت CPU و نوع هسته را برای حجم کاری بر اساس خواسته‌های قبلی تنظیم می‌کند. اگر حجم کاری از منابع CPU بیشتری استفاده کند، سرعت کلاک افزایش می‌یابد و در نهایت حجم کاری به هسته بزرگ‌تری منتقل می‌شود. اگر حجم کار از منابع کمتری استفاده کند، اندروید تخصیص منابع را کاهش می‌دهد. با ADPF، برنامه یا بازی می تواند سیگنال اضافی در مورد عملکرد و مهلت های خود ارسال کند. این به سیستم کمک می کند تا با شدت بیشتری افزایش یابد (بهبود عملکرد) و پس از اتمام بار کاری، ساعت را به سرعت پایین بیاورد (صرفه جویی در مصرف برق).
سرعت ساعت
وقتی دستگاه های اندرویدی به صورت پویا سرعت ساعت CPU خود را تنظیم می کنند، فرکانس می تواند عملکرد کد شما را تغییر دهد. طراحی کدی که به سرعت ساعت پویا می پردازد برای به حداکثر رساندن عملکرد، حفظ حالت حرارتی ایمن و استفاده کارآمد از توان مهم است. شما نمی توانید مستقیماً فرکانس های CPU را در کد برنامه خود اختصاص دهید. در نتیجه، یک راه معمول برای برنامه‌ها برای اجرای با سرعت‌های بالاتر ساعت CPU، اجرای یک حلقه مشغول در یک رشته پس‌زمینه است تا حجم کاری سخت‌تر به نظر برسد. این عمل بدی است زیرا وقتی برنامه واقعاً از منابع اضافی استفاده نمی‌کند، انرژی را هدر می‌دهد و بار حرارتی روی دستگاه را افزایش می‌دهد. CPU PerformanceHint API برای رفع این مشکل طراحی شده است. با آگاه کردن سیستم از مدت زمان واقعی کار و مدت زمان کار مورد نظر، Android می‌تواند یک نمای کلی از نیازهای CPU برنامه داشته باشد و منابع را به طور موثر تخصیص دهد. این منجر به عملکرد بهینه در سطح مصرف انرژی کارآمد می شود.
انواع هسته
انواع هسته های CPU که بازی شما روی آنها اجرا می شود یکی دیگر از فاکتورهای عملکرد مهم است. دستگاه‌های Android اغلب هسته CPU اختصاص داده شده به یک رشته را بر اساس رفتار بار کاری اخیر به صورت پویا تغییر می‌دهند. تخصیص هسته CPU در SoC هایی با انواع هسته های متعدد حتی پیچیده تر است. در برخی از این دستگاه‌ها، هسته‌های بزرگتر تنها می‌توانند برای مدت کوتاهی بدون وارد شدن به حالت حرارتی ناپایدار استفاده شوند.
بازی شما نباید به دلایل زیر سعی کند میل هسته CPU را تنظیم کند:
بهترین نوع هسته برای حجم کاری بسته به مدل دستگاه متفاوت است.
پایداری هسته های بزرگتر بر اساس SoC و راه حل های حرارتی مختلف ارائه شده توسط هر مدل دستگاه متفاوت است.
تأثیر محیطی بر حالت حرارتی می تواند انتخاب اصلی را پیچیده تر کند. به عنوان مثال، آب و هوا یا یک قاب گوشی می تواند وضعیت حرارتی یک دستگاه را تغییر دهد.
انتخاب هسته نمی تواند دستگاه های جدید با عملکرد اضافی و قابلیت های حرارتی را در خود جای دهد. در نتیجه، دستگاه ها اغلب میل پردازنده بازی را نادیده می گیرند.
نمونه ای از رفتار پیش فرض زمانبندی لینوکس
شکل 1. گاورنر می تواند 200 میلی ثانیه طول بکشد تا فرکانس CPU را بالا یا پایین کند. ADPF با سیستم مقیاس‌سنجی ولتاژ و فرکانس دینامیک (DVFS) برای ارائه بهترین عملکرد در هر وات کار می‌کند.
PerformanceHint API بیشتر از تاخیرهای DVFS خلاصه می شود
شکل 2. ADPF می داند که چگونه بهترین تصمیم را از طرف شما بگیرد
اگر کارها باید روی یک CPU خاص اجرا شوند، PerformanceHint API می داند که چگونه از طرف شما این تصمیم را بگیرد.
بنابراین، شما نیازی به استفاده از افینیت ندارید.
دستگاه ها با توپولوژی های مختلف عرضه می شوند. قدرت و ویژگی های حرارتی آنقدر متنوع هستند که در معرض توسعه برنامه قرار نگیرند.
شما نمی توانید هیچ فرضی در مورد سیستم زیربنایی که روی آن اجرا می کنید داشته باشید.
راه حل
ADPF کلاس PerformanceHintManager را ارائه می دهد تا بازی ها بتوانند نکات عملکردی را برای سرعت ساعت CPU و نوع هسته به اندروید ارسال کنند. سپس سیستم عامل می تواند تصمیم بگیرد که چگونه از نکات بر اساس SoC و محلول حرارتی دستگاه استفاده کند. اگر برنامه شما از این API همراه با نظارت بر وضعیت حرارتی استفاده می‌کند، می‌تواند به جای استفاده از حلقه‌های مشغول و سایر تکنیک‌های کدگذاری که می‌تواند باعث ایجاد throttling شود، نکات آگاهانه‌تری را به سیستم عامل ارائه دهد.
به این صورت است که یک بازی از نکات عملکرد استفاده می کند:
در Unreal، افزونه Unreal Adaptive Performance را ادغام کنید و از گزینه های مقیاس پذیری برای پشتیبانی از چندین سطح کیفیت استفاده کنید.
موضوعات IO یک جلسه دیگر دریافت می کنند
موضوعات صوتی جلسه سوم را دریافت می کنند
بازی باید این کار را زودتر انجام دهد، حداقل 2 میلی ثانیه و ترجیحاً بیش از 4 میلی ثانیه قبل از اینکه یک جلسه نیاز به افزایش منابع سیستم داشته باشد.
در هر جلسه راهنمایی، مدت زمان مورد نیاز برای اجرای هر جلسه را پیش بینی کنید. مدت زمان معمولی معادل یک بازه فریم است، اما اگر حجم کاری بین فریم ها به طور قابل توجهی تغییر نکند، برنامه می تواند از بازه زمانی کوتاه تری استفاده کند.
در اینجا نحوه عملی کردن تئوری آمده است:
PerformanceHintManager و createHintSession را راه اندازی کنید
مدیر را با استفاده از سرویس سیستم دریافت کنید و یک جلسه راهنمایی برای رشته یا گروه رشته خود ایجاد کنید که بر روی همان حجم کاری کار می کنند.
از تابع setThreadsPerformanceHintManager.Session زمانی که رشته های دیگری دارید که باید بعدا اضافه شوند استفاده کنید. به عنوان مثال، اگر بعداً موضوع فیزیک خود را ایجاد کردید و باید آن را به جلسه اضافه کنید، می توانید از این API setThreads استفاده کنید.
int[]tids=newint[3];// add all your thread IDs. Remember to use android.os.Process.myTid() as that// is the linux native thread-id.// Thread.currentThread().getId() will not work because it is jvm's thread-id.hintSession.setThreads(tids);
اگر سطوح پایین‌تر API را هدف قرار می‌دهید، باید هر بار که نیاز به تغییر شناسه‌های رشته دارید، جلسه را از بین ببرید و یک جلسه جدید ایجاد کنید.
گزارش مدت زمان واقعی کار
مدت زمان واقعی مورد نیاز برای تکمیل کار را در نانوثانیه پیگیری کنید و پس از اتمام کار در هر چرخه آن را به سیستم گزارش دهید. به عنوان مثال، اگر این برای رشته های رندر شما است، این را در هر فریم فراخوانی کنید.
برای به دست آوردن زمان واقعی قابل اعتماد، از موارد زیر استفاده کنید:
C++
clock_gettime(CLOCK_MONOTONIC,&clock);// if you prefer "C" way from <time.h>// orstd::chrono::high_resolution_clock::now();// if you prefer "C++" way from <chrono>
جاوا
System.nanoTime();
به عنوان مثال:
C++
// All timings should be from `std::chrono::steady_clock` or `clock_gettime(CLOCK_MONOTONIC, ...)`autostart_time=std::chrono::high_resolution_clock::now();// do workautoend_time=std::chrono::high_resolution_clock::now();autoduration=std::chrono::duration_cast<std::chrono::nanoseconds>(end_time-start_time).count();int64_tactual_duration=static_cast<int64_t>(duration);APerformanceHint_reportActualWorkDuration(hint_session,actual_duration);
جاوا
longstartTime=System.nanoTime();// do worklongendTime=System.nanoTime();longduration=endTime-startTime;hintSession.reportActualWorkDuration(duration);
در صورت لزوم، مدت زمان کار هدف را به روز کنید
هر زمان که مدت زمان کار مورد نظر شما تغییر کرد، برای مثال اگر بازیکن فریم در ثانیه هدف متفاوتی را انتخاب کرد، روش updateTargetWorkDuration را فراخوانی کنید تا به سیستم اطلاع دهید تا سیستم عامل بتواند منابع را مطابق با هدف جدید تنظیم کند. شما مجبور نیستید آن را در هر فریم فراخوانی کنید و فقط زمانی باید آن را فراخوانی کنید که مدت زمان هدف تغییر کند.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Performance Hint API\n\n**Released**:\n\nAndroid 12 (API Level 31) - [Performance Hint API](/reference/android/os/PerformanceHintManager)\n\nAndroid 13 (API Level 33) - [Performance Hint Manager in the NDK API](/ndk/reference/group/a-performance-hint)\n\n(Preview) Android 15 (DP1) - [`reportActualWorkDuration()`](/reference/android/os/PerformanceHintManager.Session#reportActualWorkDuration(android.os.WorkDuration))\n\nWith CPU performance hints, a game can influence dynamic CPU performance\nbehavior to better match its needs. On most devices, Android dynamically adjusts\nthe CPU clock speed and core type for a workload based on the previous demands.\nIf a workload uses more CPU resources, the clock speed is increased and the\nworkload is eventually moved to a larger core. If the workload uses less\nresources, then Android lowers resource allocation. With ADPF, the application\nor game can send an additional signal about its performance and deadlines. This\nhelps the system ramp up more aggressively (improving performance) and lower the\nclocks quickly when the workload is complete (saving power usage).\n\nClock speed\n-----------\n\nWhen Android devices dynamically adjust their CPU clock speed, the frequency can\nchange the performance of your code. Designing code that addresses dynamic clock\nspeeds is important for maximizing performance, maintaining a safe thermal\nstate, and using power efficiently. You cannot directly assign CPU frequencies\nin your app code. As a result, a common way for apps to attempt to run at higher\nCPU clock speeds is to run a busy loop in a background thread so the workload\nseems more demanding. This is a bad practice as it wastes power and increases\nthe thermal load on the device when the app isn't actually using the additional\nresources. The CPU `PerformanceHint` API is designed to address this problem. By\nletting the system know the actual work duration and the target work duration,\nAndroid will be able to get an overview of the app's CPU needs and allocate\nresources efficiently. This will lead to optimum performance at efficient power\nconsumption level.\n\nCore types\n----------\n\nThe CPU core types that your game runs on are another important performance\nfactor. Android devices often change the CPU core assigned to a thread\ndynamically based on recent workload behavior. CPU core assignment is even more\ncomplex on SoCs with multiple core types. On some of these devices, the larger\ncores can only be used briefly without going into a thermally unsustainable\nstate.\n\nYour game shouldn't try to set the CPU core affinity for the following reasons:\n\n- The best core type for a workload varies by device model.\n- The sustainability of running larger cores varies by SoC and by the various thermal solutions provided by each device model.\n- The environmental impact on the thermal state can further complicate core choice. For example, the weather or a phone case can change the thermal state of a device.\n- Core selection can't accommodate new devices with additional performance and thermal capabilities. As a result, devices often ignore a game's processor affinity.\n\n### Example of default Linux scheduler behavior\n\n**Figure 1.** Governor can take \\~200ms to ramp up or down CPU frequency. ADPF works with the Dynamic Voltage and Frequency Scaling system (DVFS) to provide best performance per watt\n\n### PerformanceHint API abstracts more than DVFS latencies\n\n**Figure 2.** ADPF knows how to make the best decision on your behalf\n\n- If the tasks need to run on a specific CPU, PerformanceHint API knows how to make that decision on your behalf.\n- Therefore, you need not use affinity.\n- Devices come with various topologies; Power and thermal characteristics are too varied to be exposed to app developer.\n- You can't make any assumptions about the underlying system you're running on.\n\nSolution\n--------\n\nADPF provides the [`PerformanceHintManager`](/reference/android/os/PerformanceHintManager)\nclass so games can send performance hints to Android for CPU clock speed and\ncore type. The OS can then decide how to best use the hints based on the SoC and\nthermal solution of the device. If your app uses this API along with thermal\nstate monitoring, it can provide more informed hints to the OS instead of using\nbusy loops and other coding techniques that can cause throttling.\n\nThis is how a game uses performance hints:\n\n1. [Create hint sessions](/reference/android/os/PerformanceHintManager#createHintSession(int%5B%5D,%20long)) for key threads that behave similarly. For example:\n - Rendering thread and its dependencies get one session\n 1. In Cocos, the main engine thread and render thread gets [one\n session](https://github.com/cocos/cocos-engine/blob/v3.8.5-dianchu/native/cocos/base/threading/MessageQueue.cpp)\n 2. In Unity, integrate [Adaptive Performance Android Provider plugin](https://docs.unity3d.com/Packages/com.unity.adaptiveperformance.google.android@1.2/manual/index.html)\n 3. In Unreal, integrate Unreal Adaptive Performance plugin and use [Scalability options](https://docs.unrealengine.com/4.27/en-US/TestingAndOptimization/PerformanceAndProfiling/Scalability/ScalabilityReference/) to support multiple quality levels\n - IO threads get another session\n - Audio threads get a third session\n2. The game should do this early, at least 2ms and preferably more than 4ms before a session needs increased system resources.\n3. In each hint session, predict the duration needed for each session to run. The typical duration is equivalent to a frame interval, but the app can use a shorter interval if the workload does not vary significantly across frames.\n\nHere is how to put the theory into practice:\n\n### Initialize PerformanceHintManager and createHintSession\n\nGet the manager using system service and create a hint session for your thread\nor thread group working on the same workload. \n\n### C++\n\n int32_t tids[1];\n tids[0] = gettid();\n int64_t target_fps_nanos = getFpsNanos();\n APerformanceHintManager* hint_manager = APerformanceHint_getManager();\n APerformanceHintSession* hint_session =\n APerformanceHint_createSession(hint_manager, tids, 1, target_fps_nanos);\n\n### Java\n\n int[] tids = {\n android.os.Process.myTid()\n };\n long targetFpsNanos = getFpsNanos();\n PerformanceHintManager performanceHintManager =\n (PerformanceHintManager) this.getSystemService(Context.PERFORMANCE_HINT_SERVICE);\n PerformanceHintManager.Session hintSession =\n performanceHintManager.createHintSession(tids, targetFpsNanos);\n\n### Set threads if necessary\n\n**Released**:\n\nAndroid 11 (API Level 34)\n\nUse the [`setThreads`](/reference/android/os/PerformanceHintManager.Session#setThreads(int%5B%5D))\nfunction of the `PerformanceHintManager.Session` when you have other threads\nthat need to be added later. For example, if you create your physics thread\nlater and need to add it to the session, you can use this `setThreads` API. \n\n### C++\n\n auto tids = thread_ids.data();\n std::size_t size = thread_ids_.size();\n APerformanceHint_setThreads(hint_session, tids, size);\n\n### Java\n\n int[] tids = new int[3];\n\n // add all your thread IDs. Remember to use android.os.Process.myTid() as that\n // is the linux native thread-id.\n // Thread.currentThread().getId() will not work because it is jvm's thread-id.\n hintSession.setThreads(tids);\n\nIf you are targeting lower API Levels, you will need to destroy the session and\nre-create a new session every time you need to change the thread IDs.\n\n### Report Actual Work Duration\n\nTrack the actual duration needed to complete the work in nanoseconds and report\nit to the system upon completion of the work on every cycle. For example, if\nthis is for your rendering threads, call this on every frame.\n\nTo get the actual time reliably, use: \n\n### C++\n\n clock_gettime(CLOCK_MONOTONIC, &clock); // if you prefer \"C\" way from \u003ctime.h\u003e\n // or\n std::chrono::high_resolution_clock::now(); // if you prefer \"C++\" way from \u003cchrono\u003e\n\n### Java\n\n System.nanoTime();\n\nFor example: \n\n### C++\n\n // All timings should be from `std::chrono::steady_clock` or `clock_gettime(CLOCK_MONOTONIC, ...)`\n auto start_time = std::chrono::high_resolution_clock::now();\n\n // do work\n\n auto end_time = std::chrono::high_resolution_clock::now();\n auto duration = std::chrono::duration_cast\u003cstd::chrono::nanoseconds\u003e(end_time - start_time).count();\n int64_t actual_duration = static_cast\u003cint64_t\u003e(duration);\n\n APerformanceHint_reportActualWorkDuration(hint_session, actual_duration);\n\n### Java\n\n long startTime = System.nanoTime();\n\n // do work\n\n long endTime = System.nanoTime();\n long duration = endTime - startTime;\n\n hintSession.reportActualWorkDuration(duration);\n\n### Update Target Work Duration when necessary\n\nWhenever your target work duration changes, for example if the player chooses a\ndifferent target fps, call the [`updateTargetWorkDuration`](/reference/android/os/PerformanceHintManager.Session#updateTargetWorkDuration(long))\nmethod to let the system know so that the OS can adjust the resources according\nto the new target. You don't have to call it on every frame and only need to\ncall it when the target duration changes. \n\n### C++\n\n APerformanceHint_updateTargetWorkDuration(hint_session, target_duration);\n\n### Java\n\n hintSession.updateTargetWorkDuration(targetDuration);"]]
