> For the complete documentation index, see [llms.txt](https://workshop-guide.magicbyte.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://workshop-guide.magicbyte.ru/mbsl-docs/modeli-vyzova-funkcii/promise-obeshanie-znacheniya.md).

# 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);
}
```