xpcom/threads/nsIThreadPool.idl
author Henri Sivonen <hsivonen@hsivonen.fi>
Fri, 06 Jul 2018 10:44:43 +0300
changeset 489140 4ef0f163fdeb9afeddd87b37bfd987298c038542
parent 414721 a26040f4d439626f98509caa71009675721d12d7
child 500901 442e20f46b5d670b0dafb158072dadde45d58e23
permissions -rw-r--r--
Bug 1402247 - Use encoding_rs for XPCOM string encoding conversions. r=Nika,erahm,froydnj. Correctness improvements: * UTF errors are handled safely per spec instead of dangerously truncating strings. * There are fewer converter implementations. Performance improvements: * The old code did exact buffer length math, which meant doing UTF math twice on each input string (once for length calculation and another time for conversion). Exact length math is more complicated when handling errors properly, which the old code didn't do. The new code does UTF math on the string content only once (when converting) but risks allocating more than once. There are heuristics in place to lower the probability of reallocation in cases where the double math avoidance isn't enough of a saving to absorb an allocation and memcpy. * Previously, in UTF-16 <-> UTF-8 conversions, an ASCII prefix was optimized but a single non-ASCII code point pessimized the rest of the string. The new code tries to get back on the fast ASCII path. * UTF-16 to Latin1 conversion guarantees less about handling of out-of-range input to eliminate an operation from the inner loop on x86/x86_64. * When assigning to a pre-existing string, the new code tries to reuse the old buffer instead of first releasing the old buffer and then allocating a new one. * When reallocating from the new code, the memcpy covers only the data that is part of the logical length of the old string instead of memcpying the whole capacity. (For old callers old excess memcpy behavior is preserved due to bogus callers. See bug 1472113.) * UTF-8 strings in XPConnect that are in the Latin1 range are passed to SpiderMonkey as Latin1. New features: * Conversion between UTF-8 and Latin1 is added in order to enable faster future interop between Rust code (or otherwise UTF-8-using code) and text node and SpiderMonkey code that uses Latin1. MozReview-Commit-ID: JaJuExfILM9

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsIEventTarget.idl"

[scriptable, uuid(ef194cab-3f86-4b61-b132-e5e96a79e5d1)]
interface nsIThreadPoolListener : nsISupports
{
  /**
   * Called when a new thread is created by the thread pool. The notification
   * happens on the newly-created thread.
   */
  void onThreadCreated();

  /**
   * Called when a thread is about to be destroyed by the thread pool. The
   * notification happens on the thread that is about to be destroyed.
   */
  void onThreadShuttingDown();
};

/**
 * An interface to a thread pool.  A thread pool creates a limited number of
 * anonymous (unnamed) worker threads.  An event dispatched to the thread pool
 * will be run on the next available worker thread.
 */
[builtinclass, scriptable, uuid(76ce99c9-8e43-489a-9789-f27cc4424965)]
interface nsIThreadPool : nsIEventTarget
{
  /**
   * Shutdown the thread pool.  This method may not be executed from any thread
   * in the thread pool.  Instead, it is meant to be executed from another
   * thread (usually the thread that created this thread pool).  When this
   * function returns, the thread pool and all of its threads will be shutdown,
   * and it will no longer be possible to dispatch tasks to the thread pool.
   *
   * As a side effect, events on the current thread will be processed.
   */
  void shutdown();

  /**
   * Get/set the maximum number of threads allowed at one time in this pool.
   */
  attribute unsigned long threadLimit;

  /**
   * Get/set the maximum number of idle threads kept alive.
   */
  attribute unsigned long idleThreadLimit;

  /**
   * Get/set the amount of time in milliseconds before an idle thread is
   * destroyed.
   */
  attribute unsigned long idleThreadTimeout;

  /**
   * Get/set the number of bytes reserved for the stack of all threads in
   * the pool. By default this is nsIThreadManager::DEFAULT_STACK_SIZE.
   */
  attribute unsigned long threadStackSize;

  /**
   * An optional listener that will be notified when a thread is created or
   * destroyed in the course of the thread pool's operation.
   *
   * A listener will only receive notifications about threads created after the
   * listener is set so it is recommended that the consumer set the listener
   * before dispatching the first event. A listener that receives an
   * onThreadCreated() notification is guaranteed to always receive the
   * corresponding onThreadShuttingDown() notification.
   *
   * The thread pool takes ownership of the listener and releases it when the
   * shutdown() method is called. Threads created after the listener is set will
   * also take ownership of the listener so that the listener will be kept alive
   * long enough to receive the guaranteed onThreadShuttingDown() notification.
   */
  attribute nsIThreadPoolListener listener;

  /**
   * Set the label for threads in the pool. All threads will be named
   * "<aName> #<n>", where <n> is a serial number.
   */
  void setName(in ACString aName);
};