Skip to content

Instantly share code, notes, and snippets.

@confused-Techie

confused-Techie/how-pulsar-works.md

Last active July 3, 2023 03:10
Show Gist options
  • Save confused-Techie/fc1a16b65762961270639c64a2c77b27 to your computer and use it in GitHub Desktop.
Save confused-Techie/fc1a16b65762961270639c64a2c77b27 to your computer and use it in GitHub Desktop.
Download ZIP
How Pulsar Works
Raw
how-pulsar-works.md

How Pulsar Works

It's no secret that Pulsar since inherited from Atom, is a big and complex application.

With many discrete, moving aspects, that not all developers have a concrete grasp on. The goal of this document is to make the architecture of Pulsar, as well as the logical flow more understandable and approachable.

This will be accomplished through a series of illustrations detailing the functional decomposition and detailed logical flow of Pulsar and it's parts, as well as lists of what's accomplished in each part.

This document is aimed at those roughly familiar with the large scale goals and features of Pulsar, as well as those with a basic understanding of the package model used to power much of Pulsar's functionality.

Birds Eye View

                                                                                                                         +----------------------+
                                                                                                                        |                      |
                                                                                                                        |    Initialization    |
                                                                                                                        | /main-process/main.js|
                                                                                                                        +----------+-----------+
                                                                                                                                   |
                                                                                                                                   |
                                                                                       +----------------------+        +-----------v------------+         +----------------------------------+
                                                                                       |                      |        |                        |         |                                  |
                                                                                       |  Main Process Tests  <--------+        Startup         +--------->       Startup w/ Squirrel        |
                                                                                       |                      |        | /main-process/start.js |         | /main-process/squirrel-update.js |
                                                                                       +----------------------+        +-----------+------------+         +----------------------------------+
                                                                                                                                   |
                                                                                                                                   |
                                                                            +----------------------------+      +------------------v---------------------+
                                                                            |                            |      |                                        |
                                                                            |       Test Runner          <------+          Application Startup           |
                                                                            | /initialize-test-window.js |      |    /main-process/atom-application.js   |
                                                                            |                            |      |                                        |
                                                                            +----------------------------+      +-------------------+--------------------+
                                                                                                                                    |
                                                                                                                   +----------------v------------------+
                                                                                                                   |                                   +--------------------------------+
                                                                                                                   |   Initialize Application Window   |                                |
                                                                                                                   | /initialize-application-window.js |     +----------------+ +-------v------------------+
                                                                                                                   |                                   +----->                | |                          |
                                                                                                                   +----------------+------------------+     |   Clipboard    | |    ApplicationDelegate   |
                                                                                                                                    |                        | /clipboard.js  | | /application-delegate.js |
                                                                                                                       +------------v-----------+            |                | |                          |
                                                                                                                       |                        |            +--+-------------+ +-------+------------------+
                                                                                                                       |       'The World'      |               |                       |
                                                                                                                       |  /atom-environment.js  <---------------+                       |
                                                                                                                       |                        |                                       |
                                                                                                                       +-+-+-+-+-+-+-+-+-+-+-+-+v---------------------------------------+
                                                                                                                       | | | | | | | | | | | | |
                                                                           +----------------------+   +------------+   | | | | | | | | | | | | |     +--------------------------+
                                                                           |   ScopeDescriptor    <---+   Config   <---+ | | | | | | | | | | | +----->    DeserializerManager   |
                                                                           | /scope-descriptor.js |   | /config.js |     | | | | | | | | | | |       | /deserializer-manager.js |
                                                                           +----------------------+   +------------+     | | | | | | | | | | |       +--------------------------+
                                                                                                                         | | | | | | | | | | |
                                                                                           +-----------------------+     | | | | | | | | | | |       +-------------------+
                                                                                           |     KeymapManager     |     | | | | | | | | | | |       |   ViewRegistry    |
                                                                                           | /keymap-extensions.js <-----+ | | | | | | | | | +-------> /view-registry.js |
                                                                                           +-----------------------+       | | | | | | | | |         +-------------------+
                                                                                                                           | | | | | | | | |
                                                                           +-------------+   +---------------------+       | | | | | | | | |         +--------------------------+  +-------------------+
                                                                           |   Tooltip   <---+   TooltipManager    <-------+ | | | | | | | +--------->    NotificationManager   |  |    Notification   |
                                                                           | /tooltip.js |   | /tooltip-manager.js |         | | | | | | |           | /notification-manager.js +--> /notification.js  |
                                                                           +-------------+   +---------------------+         | | | | | | |           +--------------------------+  +-------------------+
                                                                                                                             | | | | | | |
                                                                                            +----------------------+         | | | | | | |           +-----------------+
                                                                                            |    CommandRegistry   <---------+ | | | | | |           |    StateStore   |      +-------------+ +-------------------+
                                                                                            | /command-registry.js |           | | | | | +-----------> /state-store.js |      |   Package   | |   ThemePackage    |
                                                                                            +----------------------+           | | | | |             +-----------------+      | /package.js | | /theme-package.js |
                                                                                                                               | | | | |                                      +------^------+ +------^------------+
                                                                                        +--------------------------+           | | | | |             +---------------------+         |               |
                                                                                        |    URIHandlerRegistry    <-----------+ | | | +------------->    PackageManager   +---------+---------------+
                                                               +--------------------+   | /uri-handler-registry.js |             | | |               | /package-manager.js |                         |
                                                               | createStylesElement|   +--------------------------+             | | |               +---------------------+       +-----------------v+
                                                               | /styles-element.js |                                            | | |                                             |   ModuleCache    |
                                                               +-------------------->          +-------------------+             | | |               +-------------------+         | /module-cache.js |
                                                                                    +----------+   StyleManager    <-------------+ | +--------------->   ThemeManager    +------+  +------------------+
                                                                                               | /style-manager.js |               |                 | /theme-manager.js |      |
                                                         +-------------------------------^-----+-------------------+               |                 +-------------------+    +-v----------------------+
                                                         |  DEPRECATED_SYNTAX_SELECTORS  |                                         |                                          |   LessCompileCache     |
                                                         |/deprecated-syntax-selectors.js|     +-------------------+               |                 +-------------+          | /less-compile-cache.js |
                                                         +-------------------------------+     |   MenuManager     <---------------+----------------->   Project   +----+     +------------------------+
                                                                                               | /menu-manager.js  |               |                 | /project.js |    |
                                                                +-------------------+          +-------------------+               |                 +-------------+    |     +-------------------+
                                                                |    MenuHelpers    <----------+                                   |                                    +----->    watchPath      |
                                                                | /menu-helpers.js  |                                              |          +-----------------------+ |     | /path-watcher.js  |
                                                                +-------------------v----+--------------------------+              |          |   CommandInstaller    | |     +-------------------+
                                                                                         |    ContextMenuManager    <--------------+----------> /command-installer.js | |
                                                             +-----------------------^---+ /context-menu-manager.js |              |          +-----------------------+ |     +--------------------------------+
                                                             |    sortMenuItems      |   +--------------------------+              |                                    +----->    DefaultDirectoryProvider    |
                                                             | /menu-sort-helpers.js |                                             | +--------------------------------+ |     | /default-directory-provider.js |
                                                             +-----------------------+  +---------------------------+              | |    ProtocolHandlerInstaller    | |     +--------------------------------+
                                                                                        |    TextEditorRegistry     <--------------+-> /protocol-handler-installer.js | |
                                                             +-----------------+    +---+ /text-editor-registry.js  |              | +--------------------------------+ |     +-----------+
                                                             |   TextEditor    <----+   +---------------------------+              |                                    |     |   Model   |
                                                             | /text-editor.js |    |                                              |        +-------------------------+ +-----> /model.js |
                                                             +-----------------+    |         +---------------------+              +-------->    AutoUpdateManager    | |     +-----------+
                                                                                    |         |    HistoryManager   <--------------+        | /auto-update-manager.js | |
                                                        +----------------------+    |         | /history-manager.js |              |        +-------------------------+ |     +-----------------------------+
                                                        |    ScopeDescriptor   |    |         +---------------------+              |                                    |     |    GitRepositoryProvider    |
                                                        | /scope-descriptor.js <----+                                              |       +--------------------------+ +-----> /git-repository-provider.js |
                                                        +----------------------+                                                   |       |    WindowEventHandler    |       +-----------------------------+
                                                                                          +----------------------------------------+-------> /window-event-handler.js +-+
                                                                                          |                                        |       +--------------------------+ |     +------------------------+
                 +--------------------+ +------------+ +----------------------+           |                                        |                                    |     |        listen          |
                 |   TokenizedLine    | |   Token    | |    ScopeDescriptor   |           |                                        |                                    +-----> /delegated-listener.js |
                 | /tokenized-line.js | | /token.js  | | /scope-descriptor.js |           |                                        +----------------------------------+       +------------------------+
                 +-------------------^+ +-----------^+ +--------------------^-+           |                                                                           |
                                     |              |                       |             |                                                                           |
+-----------------------------+      |              +--------------------+  |  +----------v-----------+                                                          +----v----------+
|     TextMateLanguageMode    |      |                                   |  |  |    GrammarRegistry   |                                                          |   Workspace   |
| /text-mate-language-mode.js <----+ +---------------------------------+ |  |  | /grammar-registry.js |                                                    +-----+ /workspace.js +------+
+-----------------------------+    |                                   | |  |  +--+----+----+---+----++                                                    |     +------+-+-+-+-++      |
                                   +--------------------------------+  | |  |     |    |    |   |    |                                                     |            | | | | |       |
         +--------------------+                                     |  | |  |     |    |    |   |    |                               +---------------------v----------+ | | | | |  +----v-------------+
         | matcherForSelector |                      +--------------+--+-+--+-----v--+ |    |   |  +-v---------------------------+   |     DefaultDirectorySearcher   | | | | | |  |   StateStore     |
         |  /selectors.js     <----------------------+  NodeTreeSitterLanguageMode   | |    |   |  |     TextMateLanguageMode    |   | /default-directory-searcher.js | | | | | |  | /state-store.js  |
         +--------------------+                      | /tree-sitter-language-mode.js | |    |   |  | /text-mate-language-mode.js |   +--------------------------------+ | | | | |  +------------------+
                                   +-----------------+-------------------------------+ |    |   |  +---------------------------+-+                                      | | | | |
          +-------------------+    |                                                   |    |   |                              |     +--------------------------------+ | | | | |  +-----------------+
          |   TreeIndenter    |    |            +------------------------------------+ |    |   |  +----------------------+    |     |    RipgrepDirectorySearcher    <-+ | | | +-->    TextEditor   |
          | /tree-indenter.js <----+            |     WASMTreeSitterLanguageMode     <-+    |   |  |   ScopeDescriptor    |    |     | /ripgrep-directory-searcher.js |   | | |    | /text-editor.js |
          +-------------------+                 | /wasm-tree-sitter-language-mode.js |      |   +--> /scope-descriptor.js |    |     +--------------------------------+   | | |    +-----------------+
                                                +------+-----------------------------+      |      +----------------------+    |                                          | | |
                                                       |                                    |                                  |              +-----------------------+   | | |    +------------+
                                                       |                                    |      +-----------+               |              |    WorkspaceCenter    <---+ | +---->   Panel    |
                                                +------v--------------+                     |      |   Token   |               |              | /workspace-center.js  |     |      | /panel.js  |
                                                |       Parser        |                     +------> /token.js |               |              +-----------------------+     |      +------------+
                                                | /web-tree-sitter.js |                            +-----------+               |                                            |
                                                +---------------------+                                                        |             +------------------------+     |      +-----------+
                                                                                                  +--------------------+       |             | createWorkspaceElement <-----+------>   Task    |
                                                                                                  |    TokenizedLine   <-------+             | /workspace-element.js  |     |      | /task.js  |
                                                                                                  | /tokenized-line.js |       |             +------------------------+     |      +-----------+
                                                                                                  +--------------------+       |                                            |
                                                                                                                               |               +----------------------+     |      +----------+
                                                                                                  +--------------------+       |               |   PanelContainer     |     |      |   Dock   |
                                                                                                  |   TokenIterator    <-------+               | /panel-container.js  <-----+------> /dock.js |
                                                                                                  | /token-iterator.js |       |               +----------------------+            +----------+
                                                                                                  +--------------------+       |
                                                                                                                               |
                                                                                                +----------------------+       |
                                                                                                |    ScopeDescriptor   |       |
                                                                                                | /scope-descriptor.js <-------+
                                                                                                +----------------------+       |
                                                                                                                               |
                                                                                                    +------------------+       |
                                                                                                    |   NullGrammar    |       |
                                                                                                    | /null-grammar.js <-------+
                                                                                                    +------------------+

Initialization

Startup of Pulsar occurs within ./src/main-process/main.js.

Which Determines:

  • resourcePath
  • devResourcePath
  • stableResourcePath
  • defaultRepositoryPath

Which Sets:

  • Application Start Time

Which Does:

  • Initializes Startup of ./src/main-process/start.js

Startup

The more general startup handling of Pulsar occurs within ./src/main-process/start.js.

Which Sets:

  • Shell Start Time
  • app.allowRendererProcessReuse: false
  • app.commandLine.appendSwitch('enable-experimental-web-platform-features')
  • app.commandLine.appendSwitch('force-color-profile', config.get('core.colorProfile'))
  • app.setAppUserModelId()
  • app.on('open-file', $)
  • app.on('open-url', $)

Which Does:

  • Normalizes the resourcePath and devResourcePath
  • Uses Config to locate and read the config file
  • atomPaths.setAtomHome()
  • atomPaths.setUserData()
  • May defer to ./src/main-process/squirrel-update.js to startup if on Windows
  • May defer to ./spec/main-process/moche-test-runner.js to startup main process tests
  • May call .open() on ./src/main-process/atom-application.js

Application Startup

The proper startup of the Pulsar Application occurs within ./src/main-process/atom-application.js.

Which Sets:

  • APPLICATION_STATE_VERSION
  • Global atomApplication

Which Does:

  • Does setup of the application socket
  • Handles deprecated benchmark startup
  • Ensures to return a new instance of AtomApplication
  • Registers basic application commands
  • Initializes:
    • ApplicationMenu
    • AtomProtocolHandler
    • WindowStack
    • FileRecoveryService
    • Config
    • StorageFolder
    • AutoUpdateManager
  • May startup the package test runner
  • May quit if asked to startup in benchmark mode
  • May open previously opened files/folders
  • May open new instance of Pulsar

Initialize Application Window

Begins initialization of an individual Pulsar window, occurs within ./src/initialize-application-window.js.

Which Determines:

Which Sets:

  • Sets the global.atom to a new instance of AtomEnvironment

Which Does:

  • triggers .preloadPackages()
  • Initializes:
    • Clipboard
    • AtomEnvironment
    • ApplicationDelegate

'The World'

'The World' refers to being within the Pulsar application, most of the application occurs within here. This code lives within ./src/atom-environment.js.

An important note about being initialized within the world, there is no access to the atom global, until the initial constructor completes processing. Meaning great care must be taken to ensure if atom is available within the initialized modules.

Which Sets:

  • AtomEnvironment.version: 1 | Possibly a reference to APPLICATION_STATE_VERSION?
  • AtomEnvironment.saveStateDebounceInterval: 1000

Which Does:

  • Initializes:
    • Clipboard | Inherited from 'Initialize Application Window'
    • ApplicationDelegate | Inherited from 'Initialize Application Window'
    • DeserializerManager
    • ViewRegistry
    • NotificationManager
    • StateStore
    • Config
    • KeymapManager
    • TooltipManager
    • CommandRegistry
    • URIHandlerRegistry
    • GrammarRegistry
    • StyleManager
    • PackageManager
    • ThemeManager
    • MenuManager
    • ContextMenuManager
    • Project
    • CommandInstaller
    • ProtocolHandlerInstaller
    • TextEditorRegistry
    • Workspace
    • AutoUpdateManager
    • WindowEventHandler
    • HistoryManager
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment