# Promise (обещание значения)

Для упрощения работы с асинхронными задачами библиотека реализует механизм Promise - обещание значения. Данный объект представляет из себя обёртку результата выполнения асинхронной операции, который может быть уже доступен на момент завершения выполнения функции, а может стать доступен спустя какое-то время.

Promise может находится в трёх состояниях:

* Неразрешённое (unresolved). Результат выполнения операции ещё не доступен.
* Выполненное (fulfilled). Результат выполнения операции доступен.
* Отклонённое (rejected). Операция завершилась ошибкой и доступна информация  об ошибке, а не результат.

В библиотеке Promise представлен двумя классами MBSL\_Promise и MBSL\_PromiseRef. Ref-версия отличается тем, что хранит сильную ссылку на результат операции (и, как следствие, несовместима с примитивными типами). В остальном классы идентичны.

```clike
enum MBSL_PromiseState
{
	Unresolved,
	Rejected,
	Fulfilled
}

class MBSL_Promise<Class T> : MBSL_PromiseBase
{ 
	//Получить текущий статус 
	MBSL_PromiseState GetState();
	//Добавить обработчик отклонения Promise (при переходе в rejected)
	MBSL_PromiseBase WhenRejected(MBSL_TypedAction1<MBSL_Exception> handler);
	//Добавить обработчик выполнения Promise (при переходе в fulfilled)
	MBSL_Promise<T> WhenFulfilled(MBSL_TypedAction1<T> handler);
	//Добавить обработчик разрешения Promise (при переходе в rejected или fulfilled)
	MBSL_PromiseBase WhenResolved(MBSL_TypedAction1<MBSL_PromiseBase> handler);
	
	//Создать promise из источника (см. далее)
	static MBSL_Promise<T> FromSource(MBSL_PromiseSource<T> source);
	//Создать promise в состоянии fulfilled с указанным результатом
	static MBSL_Promise<T> Fulfilled(T result);
	//Создать promise в состоянии rejected с указанным результатом
	static MBSL_Promise<T> Rejected(MBSL_Exception exception);
}
```

Для получения результата Promise к нему необходимо прикрепить обработчик, используя WhenFulfilled для результата операции и WhenRejected для ошибки при выполнении операции. Если на момент прикрепления обработчика результат или ошибка уже доступны, то обработчик будет вызван сразу.

## Создание Promise

Библиотека поддерживает 3 способа создания Promise:

* Уже выполненный Promise с помощью Fulfilled. Используется, если результат доступен на момент создания Promise.
* Уже отклонённый Promise c помощью Rejected. Используется, если ошибка известна на момент создания Promise.
* Неразрешённый Promise из источника с помощью FromSource. Используется, если результат или ошибка недоступны на момент создания и позволяет асинхронно выполнить Promise.

Источником для Promise служит специальный класс MBSL\_PromiseSource. В отличие от Promise, этот класс не сохраняет результаты, а лишь используется для передачи результата или ошибки для Promise, поэтому перед вызовом его методов Fulfill/Reject необходимо создать из него все Promise. Каждый созданный Promise может быть выполнен или отклонён только один раз, поэтому после вызова Fulfill/Reject на PromiseSource более его использовать не стоит.

```clike
class MBSL_PromiseSource<Class T> : Managed
{
	//Выполнить все созданные из этого источника Promise с результатом
	void Fulfill(T result);
	//Отклонить все созданные из этого источника Promise с ошибкой
	void Reject(MBSL_Exception exception);
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://workshop-guide.magicbyte.ru/mbsl-docs/modeli-vyzova-funkcii/promise-obeshanie-znacheniya.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.